GitLab 提交权限校验脚本
.git/hooks 目录详解与配置指南
一、什么是 .git/hooks？
.git/hooks 是 Git 仓库中一个隐藏目录，用于存放 钩子脚本（Hook Scripts）。这些脚本会在 Git 执行特定操作（如提交、推送、合并）的前/后自动触发，允许开发者自定义逻辑（如代码校验、权限验证、自动化流程）。
二、钩子分类（按作用场景）
| 类型 | 触发时机 | 常见钩子名称 | 是否推送到远程仓库 | 权限要求 |
|---|---|---|---|---|
| 客户端钩子 | 用户本地操作（提交、推送、合并等） | pre-commit、commit-msg、pre-push | 否（仅本地生效） | 普通开发者权限 |
| 服务端钩子 | 远程仓库接收代码时（如 GitLab 服务器） | pre-receive、update、post-receive | 否（需手动部署到服务端） | 服务端管理员权限 |
三、客户端钩子：本地仓库配置（以 pre-commit 为例）
1. 目录位置
- 路径：
<本地仓库>/.git/hooks/（注意：.git是隐藏目录，需显示隐藏文件）。 - 默认文件：Git 会提供
.sample后缀的钩子模板（如pre-commit.sample），可复制重命名后编辑。
2. 配置步骤
步骤 1：创建/编辑钩子脚本
cd your-repo/.git/hooks/
# 复制模板（可选）
cp pre-commit.sample pre-commit
# 或直接创建新文件
nano pre-commit
步骤 2：编写脚本（示例：检查代码格式）
#!/bin/sh
# pre-commit：提交前检查代码格式
echo "正在检查代码格式..."# 执行代码检查命令（如 ESLint、Pylint）
if [ "$(git diff --cached --name-only | grep -e '\.js$\|\+.ts$')" ]; thennpx eslint . --ext .js,.ts --fixif [ $? -ne 0 ]; thenecho "Error: 代码格式检查失败，提交终止！"exit 1fi
fiexit 0
步骤 3：赋予执行权限
chmod +x pre-commit
步骤 4：验证效果
git commit -m "test" # 触发 pre-commit 钩子
四、服务端钩子：以 GitLab 为例（pre-receive 钩子）
服务端钩子在 Git 服务器接收代码时触发，需在服务器端仓库的 .git/hooks/ 目录配置（需管理员权限）。
1. 适用场景
- 权限校验（如用户提交需审批）
- 分支保护（如禁止直接推送主分支）
- 合规检查（如 commit 信息必须符合规范）
2. 配置步骤（以 GitLab 服务器为例）
步骤 1：登录服务器并定位仓库
# 服务器端仓库路径（示例）
cd /var/opt/gitlab/git-data/repositories/<group-name>/<project-name>.git/hooks/
步骤 2：创建 pre-receive 脚本（示例：调用 API 校验权限）
{insert\_element\_0\_}
步骤 3：赋予执行权限
chmod +x pre-receive
步骤 4：验证效果
# 从客户端推送代码，触发服务端钩子
git push origin main
五、常用钩子列表
| 钩子名称 | 触发时机 | 典型用途 |
|---|---|---|
pre-commit | git commit 命令执行前 | 代码格式检查、单元测试、敏感信息扫描 |
commit-msg | 提交信息写入前（可修改提交信息） | 验证 commit message 格式（如 Jira 单号） |
pre-push | git push 命令执行前 | 跨仓库检查、依赖项校验、集成测试 |
pre-receive | 服务端接收推送前（仅服务端钩子） | 权限校验、分支保护、合规性检查 |
post-receive | 服务端接收推送后（仅服务端钩子） | 触发 CI/CD 流程、通知系统、更新镜像仓库 |
六、最佳实践
- 避免硬编码路径：使用相对路径或环境变量，确保钩子在不同环境下正常运行。
- 添加错误处理：用
try-catch或if判断防止钩子意外终止操作。 - 客户端钩子不推送到远程：
.git/hooks/目录不会被 Git 跟踪，需手动在每个客户端配置（或通过项目模板分发）。 - 服务端钩子高可用：在分布式系统中，需确保钩子脚本部署在所有 Git 节点（如 GitLab 的 Gitaly 集群）。
- 使用工具简化管理：
- Husky（客户端）：简化 Git 钩子管理，支持 JavaScript/TypeScript（适用于 Node.js 项目）。
- GitLab CI/CD：结合
pre-receive钩子实现更复杂的流水线校验。
七、常见问题
-
钩子不生效？
- 检查脚本是否有执行权限（
chmod +x hook-name）。 - 确认钩子名称正确（如
pre-commit而非pre-commit.sh）。 - 客户端钩子仅在本地生效，服务端钩子需部署到服务器。
- 检查脚本是否有执行权限（
-
如何调试钩子？
- 在脚本中添加日志（如
echo "Debug: $var" >> hook.log）。 - 使用
git commit --no-verify跳过客户端钩子（临时禁用）。
- 在脚本中添加日志（如
-
GitLab 替代方案：Webhook
- 若无法直接修改服务端钩子，可通过 GitLab 的 Webhook（设置 → 集成 → Webhooks）实现类似功能，在推送后触发外部服务（如校验接口）。
通过合理配置 .git/hooks，可以将代码质量检查、权限控制、自动化流程等逻辑无缝集成到 Git 工作流中，提升团队协作效率和代码合规性。