version-control

使用 Git 进行版本控制

这项技能可帮助 AI Agent 执行各类基于 Git 的版本控制任务，从初始化仓库、创建原子提交，到协调分支策略、解决合并冲突，以及通过钩子配置自动化。它涵盖日常工作流和专业团队协作所需的高级操作。

工作流

1. 检查仓库状态：运行 git status、git log --oneline -10 和 git branch -a，了解当前分支、未提交的更改、近期历史记录以及可用的远程仓库。这些上下文信息有助于判断哪些操作可以安全执行。

2. 暂存并提交更改：将相关更改归为原子提交。编写提交消息时，先用简洁的摘要行（不超过 50 个字符），再空一行；如果更改并非简单明了，则添加说明正文。如果项目有既定的提交规范（如 Conventional Commits、Angular 风格等），请遵循该规范。

3. 分支管理：从合适的基础分支创建功能、修复或发布分支。使用一致的命名规范，例如 feat/short-description、fix/issue-123 或 release/1.2.0。合并后删除过期分支，保持分支列表整洁。

4. 与远程仓库同步：定期获取并拉取更新，以保持最新状态。首次推送功能分支时使用 -u 标志。合并前，将基础分支变基或合并到功能分支，以便尽早在隔离环境中解决冲突。

5. 解决冲突：发生冲突时，检查冲突文件，了解更改的双方，选择正确的解决方案（或合并双方内容），使用 git add 将文件标记为已解决，然后完成合并或变基。解决后务必运行测试，确认结果正确。

6. 使用钩子和 CI 实现自动化：配置 Git 钩子（使用 pre-commit 进行 lint 和格式化检查、使用 commit-msg 验证提交消息、使用 pre-push 运行测试），并确保 .gitignore 涵盖构建产物、环境文件和操作系统元数据。集成 CI 流水线，在每次推送时执行质量门禁。

支持的技术

• Git（CLI、libgit2）
• 平台：GitHub、GitLab、Bitbucket、Azure DevOps
• CLI 工具：gh（GitHub CLI）、glab（GitLab CLI）
• 钩子框架：Husky、pre-commit、Lefthook
• 分支模型：GitFlow、GitHub Flow、主干开发

用法

用通俗的语言描述需求，即可让 Agent 执行任意 Git 操作。示例：

• “为新的身份验证模块创建一个功能分支，并提交我已暂存的更改。”
• “解决 src/config.ts 中的合并冲突并完成合并。”
• “为包含虚拟环境的 Python 项目配置 .gitignore。”
• “将我的分支变基到 main 上，并强制推送整理后的历史记录。”

每次执行破坏性操作前，Agent 都会检查仓库状态；在运行 reset --hard、push --force 或会改写历史记录的 rebase 等命令前，也会先向你确认。

示例

示例 1 — 解决合并冲突

场景：你当前位于分支 feat/user-profile，想要合并 main，但 src/utils/format.ts 中存在冲突。

# Attempt the merge
git merge main
# Output: CONFLICT (content): Merge conflict in src/utils/format.ts

# Inspect the conflict markers
git diff --name-only --diff-filter=U
# src/utils/format.ts

冲突文件内容如下：

function formatDate(date: Date): string {
<<<<<<< HEAD
  return date.toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" });
=======
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
>>>>>>> main
}

解决方案：main 版本使用了更现代的 Intl.DateTimeFormat API，因此更值得采用。接受该版本，移除冲突标记，然后完成合并：

function formatDate(date: Date): string {
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
}

# Mark resolved and commit
git add src/utils/format.ts
git commit -m "merge main into feat/user-profile, adopt Intl.DateTimeFormat"

示例 2 — 设置分支策略（GitHub Flow）

场景：一个小团队希望采用轻量级分支模型，以支持持续部署。

# Ensure main is the default and protected branch
gh repo edit --default-branch main

# Create a feature branch from main
git checkout main && git pull
git checkout -b feat/dark-mode

# ... develop and commit ...
git add .
git commit -m "feat: add dark-mode toggle to settings page

Reads user preference from localStorage and applies the
'dark' class to <html>. Falls back to OS preference via
prefers-color-scheme media query."

# Push and open a pull request
git push -u origin feat/dark-mode
gh pr create \
  --title "feat: add dark-mode toggle" \
  --body "## Summary
- Adds a toggle in Settings that persists to localStorage
- Respects OS-level dark mode preference as default

## Test plan
- [ ] Toggle switches theme immediately
- [ ] Preference persists across page reloads
- [ ] Falls back to OS preference for new users"

# After review and CI pass, merge via GitHub
gh pr merge --squash --delete-branch

要点：main 始终处于可部署状态；每项更改都通过 PR，并经过审查和 CI 检查；合并后删除分支，避免分支列表杂乱。

最佳实践

• 编写原子提交。 每个提交都应代表一个逻辑变更，并且单独即可编译通过并通过测试。这样可以确保 bisect、revert 和 cherry-pick 可靠运行。
• 切勿提交机密信息。 在首次提交前，将 .env、凭据文件和私钥添加到 .gitignore。使用 git-secrets 或 trufflehog 等工具扫描意外泄露的信息。
• 变基功能分支，合并到 main。 变基可使功能分支历史保持线性，便于审查；合并到 main 则会保留合并提交，作为明确的集成节点。
• 使用 --force-with-lease，而不是 --force。 如果远程有尚未获取的提交，该命令会失败，从而防止覆盖队友的工作。
• 为发布添加标签。 每次生产发布都使用附注标签（git tag -a v1.2.0 -m "Release 1.2.0"），这样始终可以追溯已部署代码对应的特定提交。
• 完善 .gitignore。 从适用于语言或框架的模板（github/gitignore）开始，并添加针对项目的条目，以忽略构建输出、编辑器配置和本地环境文件。

边缘情况

• 分离 HEAD 状态：如果用户已检出某个标签或特定提交，请在提交前提醒他们。建议先创建分支，以避免产生孤立提交。
• 大型二进制文件：Git 并非为大型二进制文件而设计。对于图像、模型或视频等资源，建议使用 Git LFS，并添加相关的 LFS 跟踪规则。
• 浅克隆：在浅克隆（--depth 1）中，blame、log 和 bisect 等操作可能会失败。在执行依赖历史记录的操作前，运行 git fetch --unshallow。
• 子模块和单体仓库：如果项目使用子模块，请确保将 git submodule update --init --recursive 加入设置说明。对于单体仓库，提交时应遵守各软件包的变更边界。
• 强制推送后的分支分歧：如果队友对共享分支执行了强制推送，建议先运行 git fetch，然后仅在确认不会丢失本地工作后运行 git reset --hard origin/<branch>。请先与团队协调。