Git 工作流指引

那些让人反复踩坑的 Git 场景

日常协作中，Git 的大部分问题并不源于命令本身，而是源于「下一步该做什么」的判断失误。常见的几个场景：

• PR 标题写成 feat: update，描述里全是分支名，reviewer 只能靠猜改动意图。
• 已合并的分支堆积在本地和远程，git branch 列出来几百条，清理时怕误删未合并的分支。
• 多人协作的合并冲突，不同区域冲突好处理，架构层面的冲突往往需要人拍板，自动脚本帮不上忙。
• Monorepo 里打 v2.1.0 标签，不知道指的是哪个包，CI 和发布脚本拿到的语义是模糊的。
• 新仓库首次 git add . 把 node_modules/ 和 .env 全提交进去了，事后清理成本高。

技能的工作方式

这个技能把上述场景拆成结构化步骤，每一步都明确要执行的命令和校验点。它不做「一键完成」的承诺，而是按工作流分步推进，每一步产出可检查的结果。

A. 准备 Pull Request

1. 收集上下文：运行 git log main..HEAD --oneline 列出分支提交，git diff main...HEAD --stat 查看改动文件，git status 检查未提交工作。
2. 起草 PR 内容：标题不超过 70 字符，描述改动而非分支名，正文说明「为什么」、列出关键改动、附测试计划。摘要基于提交历史生成，不靠记忆。
3. 推送并创建：git push -u origin HEAD 后用 gh pr create 创建，正文模板见 references/template.md。
4. 校验：gh pr view --web 在浏览器打开确认。

B. 安全清理已合并分支

1. 切到 main 并拉取最新：git checkout main && git pull。
2. 列出已合并分支（排除 main、master、develop）。
3. 删除本地已合并分支：git branch --merged main 过滤后逐条 git branch -d。
4. 修剪远程跟踪引用：git fetch --prune。

C. 合并冲突解决

1. 评估范围：git fetch origin 后尝试 git merge origin/main --no-commit --no-ff，用 git diff --name-only --diff-filter=U 列出冲突文件。
2. 逐文件解决：不同区域保留双方改动；架构冲突时倾向 main 方案并在此之上重做 PR 意图。
3. 若 rebase 更干净（提交少、无共享历史）：git rebase origin/main，逐提交解决后 git rebase --continue。
4. 若 rebase 混乱（多冲突、架构分歧）：中止后提取有用代码 git show origin/branch:path > /tmp/extracted.txt，手动应用到 main，关闭原 PR 并说明。

D. Monorepo 发布标签

标签作用域到包：git tag {package-name}-v{semver}（如 contextbricks-v2.1.0），避免 monorepo 中 v2.1.0 的歧义。

E. 先建 .gitignore 再初始化

新仓库在首次 git add 前先写 .gitignore（含 node_modules/、.wrangler/、dist/、.env 等）。若 node_modules 已被跟踪：git rm -r --cached node_modules/ 后提交移除。

F. 私有仓库许可证审计

发布前用 gh repo view --json visibility 检查可见性；若为 PRIVATE，确保 LICENSE 含专有声明、package.json 含 "license":"UNLICENSED" 与 "private":true、README 无「欢迎贡献」。

适用边界与注意点

• 不适用于非常规的底层 Git 操作（如恢复误删提交），需结合具体情形判断。
• 技能给出步骤，不替代对仓库状态的真实检查。执行前请确认当前分支、远程跟踪状态和工作区是否干净。
• 冲突解决中「架构分歧」的判断需要人介入，技能提供分支策略和代码提取工具，但最终取舍取决于项目实际情况。