大型项目 Git 操作与推送规范

适配 Vue3 + NestJS 前后端分离项目，基于简化 Git-Flow 工作流，强制执行线性提交历史、规范分支命名、标准化提交信息、安全推送与回滚，配套本地 Git Hooks 自动校验与服务端 CI 兜底，从源头杜绝团队 Git 混乱问题。

一、分支管理规则（全员强制）

所有公共分支禁止本地直接推送，仅可通过 PR/MR 合并；个人功能分支自主管理，严格遵循命名规范。

注：develop 集成分支在本项目暂不引入（单主干 + squash 合并已满足当前团队规模），后续团队扩容或需长期并行多版本时再评估引入并升版本文档。

1.1 分支命名强制规范（刚性要求）

统一采用全小写 + 短横线分隔（kebab-case），禁止中文、大写字母、下划线、空格、特殊符号，兼容 Windows 终端、CI/CD 流水线、服务器脚本，杜绝编码解析异常。hotfix 分支必须包含问题编号或故障关键词，禁止无意义纯数字命名（示例：hotfix/login-npe-fix、hotfix/order-500-error）。

# ✅ 标准正确示例
feature/user-module
feature/exam-score-calc
hotfix/redis-connection-pool-bug
release/v2.1.0

# ❌ 严格禁止示例
feature/用户模块
feature/Exam_Score
feature/user_module
hotfix/RedisBug

二、提交信息规范（Commit Message）

2.1 标准格式

<类型>(<范围>): <简短清晰描述>

完整类型枚举与 body 格式以编码规范 §10.2 Conventional Commits 为准；subject 不超过 50 字符，项目优先中文。

2.2 原子提交铁律（核心红线）

一个 Commit 只解决一个独立逻辑问题，严禁混合提交（修复 Bug 夹杂新功能、多模块无关改动合并一次提交），违规需拆分后重新提交。

2.3 规范示例

feat(exam): 新增万人考试异步判分接口
fix(redis): 修复高并发下连接池耗尽问题
chore(docker): 更新 wsl-nginx 部署配置

❌ 严格禁止：更新代码、修复问题、优化代码、111 等无意义、模糊化提交信息。

三、标准开发推送流程（全员统一，唯一标准）

核心原则：强制 fetch + rebase，全程保持线性干净提交历史，彻底杜绝多余 Merge 污染分支，团队统一唯一工作流。

# 1. 切换个人功能分支
git checkout feature/xxx

# 1.5 多设备/多人协作分支必须同步自身远端分支
# 独占本地分支可跳过，跨设备、协作者开发必须执行
git pull origin feature/xxx --rebase

# 2. 拉取远端所有最新代码（仅拉取不合并）
git fetch origin

# 3. 基于远端 master 变基，同步最新主干代码
git rebase origin/master

# ⚠️ Rebase 冲突标准处理
# 1. 手动解决文件内所有冲突标记
# 2. 标记已解决文件
git add .
# 3. 继续变基流程（禁止直接新建 commit 掩盖冲突）
git rebase --continue
# 放弃本次变基（改动废弃场景）
git rebase --abort
# 跳过当前冲突提交（极少场景使用）
git rebase --skip

# 4. 核对本地代码变更
git status
git diff

# 5. 精准提交（优先指定文件，杜绝全量盲目提交）
git add src/xxx.ts

# 6. 规范提交代码
git commit -m "feat(模块): 具体功能描述"

# 7. 推送远端分支（首次推送新建远程分支，后续迭代直接 git push）
git push -u origin feature/xxx

3.1 .gitignore 强制要求

环境变量、密钥、IDE 配置、编译产物、日志文件严禁提交，完整清单与例外规则以编码规范 §10.3 为唯一权威口径（含 .env.docker.example 例外、server/uploads/、大二进制文件 10MB 上限），不再单独维护简版清单。

四、PR/MR 合并规范（区分分支来源 · 强制合并策略）

根据不同分支类型，严格区分 PR 目标分支、合并策略，所有合并操作必须通过平台 PR/MR 完成，禁止本地直接合并推送公共分支。

4.1 功能分支（feature/xxx）合入 master

• 目标分支：统一选择 master
• 合并策略：强制使用 Squash and Merge（压缩合并），将功能分支所有零散开发提交压缩为一条完整、规范的功能提交，彻底清理开发过程中的琐碎迭代记录，保证主干历史极简干净
• 前置要求：发起 PR/MR 前，必须完成 rebase origin/master 同步主干代码、解决全部冲突，禁止携带冲突、滞后代码提合并

4.2 发布/热修复分支（release/vx.y.z、hotfix/xxx）合入 master

• 目标分支：统一选择 master
• 合并策略：使用 Create a merge commit（保留独立合并节点），清晰留存版本发布、线上热修复的完整记录，便于后续版本回溯、问题溯源
• 若存在进行中的 release 分支，按 Hotfix 双分支合并流程先合 release 验证再回合 master，双分支同步后确认无差异遗漏（编码规范 §10.1）

4.3 通用强制执行要求

1. 提交 PR/MR 时，完善填写变更内容、功能实现说明、自测结果、关联需求/问题工单号，指定专属代码审核人；AI 辅助生成代码须在 PR 描述中标注（编码规范 §16）
2. 所有变更必须通过代码评审、无异议后方可执行合并，严禁私自合并；评审人须核验门禁命令执行日志（过渡期要求，编码规范 §15）
3. 合并完成后必须清理远端废弃分支：平台勾选「删除源分支」，或手动执行 git push origin --delete <分支名>，杜绝远程无效分支堆积
4. Squash 合并追溯规范：PR 标题必须精准概括全部功能变更，严禁使用「合并代码」「更新代码」等模糊描述；PR 描述中必须附带功能分支核心提交列表或完整变更摘要，保障代码追溯、git blame 信息可溯源

五、操作红线禁止规则（违规直接回滚整改）

• ❌ 禁止直接 git push 推送 master / release 所有公共分支
• ❌ 禁止提交 .env、私钥、数据库密码、接口密钥等敏感隐私配置（编码规范 §11.1 红线）
• ❌ 禁止推送编译报错、运行异常、功能残缺的无效代码
• ❌ 禁止对 master 分支执行 git push -f 强制推送（无任何豁免）
• ✅ 个人独占、未多人协作的 feature 分支，特殊场景需覆盖历史，必须使用安全指令：git push --force-with-lease（校验远端更新，杜绝误覆盖他人代码）
• ✅ 多人协作分支，全程禁止任何强制推送操作

六、代码冲突标准处理方案

团队统一使用 Rebase 模式，废弃单纯 Merge 模式，保证历史整洁统一。

# 同步主干并变基
git fetch origin
git rebase origin/master

# 手动解决所有冲突后执行
git add .
git rebase --continue

# 放弃本次变基操作
git rebase --abort

核心要求：禁止解决冲突后直接手动 commit 提交，必须通过 --continue 完成流程，保留完整提交链路。

七、错误推送回滚方案（分场景、零事故）

7.1 场景一：本地/私有独占 feature 分支（可重置历史）

仅适用于未被他人拉取、单人独占的私有分支：

git log --oneline
git reset --hard <commit-id>
git push --force-with-lease

7.2 场景二：公共分支（master/release）已推送远端（安全回滚）

严禁 reset + 强制推送，使用 revert 生成反向提交，不破坏团队公共历史，全员可正常同步代码。

# 普通提交回滚
git log --oneline
git revert <错误commit-id>
git push origin master

# 合并提交（Merge Commit）专属回滚（必须加 -m 参数）
# -m 1 含义：保留第一个父节点（默认为主干 master），仅撤销分支合并进来的改动
# 不确定父节点顺序时，执行 git show <merge-commit-id> 查看父节点列表，避免回滚错乱
git revert -m 1 <merge-commit-id>
git push origin master

八、自动化 Git Hooks 强制校验（源头拦截违规操作）

通过本地钩子脚本，自动拦截不规范分支名、不合法提交信息，无需人工审核，自动落地规范。落地方式：钩子脚本入库 scripts/git-hooks/，随 husky（计划 2026-Q3）接管；husky 就绪前可手动复制到 .git/hooks/ 过渡。

8.1 分支名校验脚本（pre-commit）

#!/bin/bash
# 强制校验分支命名规范，支持临时跳过机制

BRANCH_NAME=$(git branch --show-current)

# 紧急场景可临时跳过校验：SKIP_BRANCH_CHECK=1 git commit -m "xxx"
if [ "$SKIP_BRANCH_CHECK" = "1" ]; then
    exit 0
fi

# 豁免公共分支（master/release）：公共分支禁止本地提交推送（第五章红线），
# 本地临时提交（如配合 SKIP 机制修复历史）不应被命名规则误杀
if echo "$BRANCH_NAME" | grep -qE '^(master|release/v[0-9]+\.[0-9]+\.[0-9]+)$'; then
    exit 0
fi

# 多级分支名（如 feature/xxx-coop）允许斜杠分段
if ! echo "$BRANCH_NAME" | grep -qE '^(feature|hotfix)/[a-z0-9]+([-/][a-z0-9]+)*$|^release/v[0-9]+\.[0-9]+\.[0-9]+$'; then
    echo "❌ 提交失败：当前分支命名不规范！"
    echo "当前分支：$BRANCH_NAME"
    echo "规范格式：feature/xxx、hotfix/xxx、release/vx.y.z（全小写、连字符分隔）"
    echo "紧急跳过：SKIP_BRANCH_CHECK=1 git commit -m \"你的提交信息\""
    exit 1
fi

exit 0

8.2 提交信息校验脚本（commit-msg）

#!/bin/bash
# 强制校验 commit 提交信息格式

COMMIT_MSG_FILE="$1"
FIRST_LINE=$(head -n 1 "$COMMIT_MSG_FILE")

# 紧急场景可临时跳过校验：SKIP_COMMIT_CHECK=1 git commit -m "xxx"
if [ "$SKIP_COMMIT_CHECK" = "1" ]; then
    exit 0
fi

# 豁免 git 自动生成提交（merge/revert/fixup 等），避免误杀
if echo "$FIRST_LINE" | grep -qE '^(Merge|Revert|fixup!|squash!)'; then
    exit 0
fi

# 仅校验首行，支持多行 body（与 Conventional Commits 格式一致）
if ! echo "$FIRST_LINE" | grep -qE '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+'; then
    echo "❌ 提交失败：Commit 信息不符合团队规范！"
    echo "当前提交：$FIRST_LINE"
    echo "标准格式：类型(模块): 简短描述"
    echo "示例：feat(user): 新增用户登录功能"
    echo "紧急跳过：SKIP_COMMIT_CHECK=1 git commit -m \"你的提交信息\""
    exit 1
fi

exit 0

8.3 一键安装授权命令（项目根目录执行，Windows 请使用 Git Bash / WSL 终端）

# 先校验钩子脚本文件是否存在，避免 CI 环境、新克隆项目执行报错
if [ ! -f ".git/hooks/pre-commit" ] || [ ! -f ".git/hooks/commit-msg" ]; then
    echo "❌ 钩子脚本文件不存在，请先将 scripts/git-hooks/ 下的脚本复制到 .git/hooks/ 目录"
    exit 1
fi

# 赋予钩子脚本执行权限，自动适配 Linux/Mac/Windows Git 环境
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg

# 脚本有效性校验（防止文件缺失、命名错误导致校验失效）
if [ -x ".git/hooks/pre-commit" ] && [ -x ".git/hooks/commit-msg" ]; then
    echo "✅ Git 自动化校验钩子安装并授权成功"
else
    echo "❌ 钩子脚本安装失败，请检查文件是否存在、命名是否正确"
    exit 1
fi

8.4 全局提交模板配置（可选）

支持全局与项目级双模板优先级配置：全局模板为用户根目录 ~/.gitmessage，全项目通用；项目级私有模板命名为 .gitmessage.local，必须加入 .gitignore 忽略，杜绝误提交至代码仓库。项目级模板优先级高于全局模板。

# <类型>(<模块>): 简短描述
# 关联: #ISSUE-编号
# 合法类型: feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert

# 全局模板配置（全项目生效）
git config --global commit.template ~/.gitmessage

# 项目级模板配置（仅当前项目生效，优先级更高）
git config --local commit.template .gitmessage.local

九、服务端 CI 兜底校验（最终安全防线）

本地 Git Hooks 可被人为跳过（删除脚本、SKIP 环境变量跳过参数），为杜绝违规代码入库、实现合规闭环，必须配置服务端 CI 流水线强制校验（Gitee Actions，对齐编码规范 §15 门禁规范，计划 2026-Q3），所有远端推送、PR/MR 合并均由服务端二次校验，无法绕过，作为团队规范最后一道安全防线。

落地状态（v1.1）：兜底校验已实现为 scripts/ci-git-guard.sh 并接入 CI 流水线 git-guard job（.github/workflows/ci.yml，任意分支推送触发，needs 阻断后续构建）；管理员豁免经 secrets 注入 GIT_GUARD_EXEMPT=1；敏感文件口径：仅拦截新增（server/.env 为历史遗留已跟踪文件，含 7 项密钥，存量变更另行治理）；三场景实测（非法分支名/非法提交信息/新增敏感文件）均拦截成功。

9.1 CI 核心校验规则（强制启用）

触发条件：任意分支推送代码、提交 PR/MR 时自动触发。

1. 分支命名合法性校验：严格匹配规范分支格式，拒绝非法命名分支推送，规则同本地 Hooks：仅允许 feature/xxx、hotfix/xxx、release/vx.y.z 规范分支，禁止中文、大写、特殊符号、非法前缀
2. Commit 信息格式校验：遍历本次推送新增 commit 记录，强制校验提交信息格式，拦截无意义、不规范提交（如 更新代码、修复问题、111 等模糊描述），严格匹配 type(scope): desc 规范格式
3. 禁止敏感文件提交校验：拦截 .env、密钥、私钥、数据库配置等敏感文件推送，杜绝隐私信息泄露风险（与编码规范 §10.3 / §11.1 红线联动）
4. 既有门禁项：pnpm lint --max-warnings 0 / pnpm format:check / pnpm type-check / pnpm test / pnpm audit --audit-level high（编码规范 §15.1）

9.2 流水线拦截逻辑

1. 任意一项校验不通过，直接终止 CI 流水线、拦截代码合并、阻断版本入库
2. 输出明确错误日志，提示违规类型、修改规范，引导开发者整改后重新推送
3. 仅管理员可特殊豁免（生产紧急故障兜底，留审计日志），常规场景全员强制校验

9.3 落地价值

• 彻底杜绝「本地跳过 Hooks、远端违规入库」的漏洞
• 实现本地主动校验 + 服务端强制兜底的双重防护体系
• 统一合并策略：feature 合入 master 使用 Squash 压缩合并，hotfix/release 合入 master 使用保留节点合并

十、团队落地检查清单（必做）

• ✅ 将本规范录入项目 Wiki、README 指引，全员熟读执行
• ✅ 代码仓库开启分支保护：master 禁止直接推送，强制开启 PR/MR + 代码评审（Gitee 仓库保护）
• ✅ 所有团队成员安装本地 Git Hooks 校验脚本（§8.3）
• ✅ 团队统一唯一工作流：全程 fetch + rebase，废弃 merge 合并开发模式
• ✅ 公共分支回滚统一使用 revert，禁止 reset 强制推送
• ✅ 强制删除合并完成的远端废弃 feature 分支
• ✅ 开启服务端 CI 兜底校验（§9），拦截本地 Hooks 绕过违规提交

十一、审核修订记录（原提案 → 本规范定稿）

注：原提案尾部标注「部分内容可能由 AI 生成」，本规范（1.1版本）已经人工逐条审核修订（上表 R1~R10）并在项目进行了实测验证，未发现任何问题。

文档维护负责人：午阳方舟
变更评审人：清流人间
修订日期：2026-08-15