git-expert

Git 专家技能

安装

此技能会调用 git CLI。如果尚未安装 Git，请先安装：

• Windows：从 git-scm.com 下载，或运行 winget install --id Git.Git -e --source winget
• macOS：运行 brew install git，或安装 Xcode CLI 工具：xcode-select --install
• Linux：运行 apt-get install git（Debian/Ubuntu）、dnf install git（Fedora）或 pacman -S git（Arch）

验证：git --version

速查表与最佳实践

必备命令（节省令牌）：

• git status -s — 简短状态；git add -p — 暂存代码块；git diff --cached — 检查已暂存的内容
• git switch -c <branch> 或 git checkout -b <branch> — 创建新分支；git branch — 列出分支
• git log --oneline -5 — 简洁历史记录；git log --follow <file> — 跟踪重命名
• git restore <file> — 丢弃未暂存的更改；git reset --soft HEAD~1 — 撤销上次提交（保留更改）
• 先运行 git fetch，再运行 git merge 或 git pull — 优先使用 fetch+merge，避免盲目 pull

技巧： 设置 git config --global color.ui auto 和 user.name/user.email。积极使用 .gitignore。合并功能分支时，优先使用 git merge --squash，以保持历史记录整洁。使用 git cherry-pick <commit> 引入单个提交。未经团队同意，绝不要变基已推送的提交。

认证与培训

免费 / 官方资源： Atlassian Git Tutorials（从入门到进阶）。Microsoft Learn – GitHub Training（GitHub Foundations 学习路径）。GitHub Learn（Git + GitHub）。没有单一的“Git 认证”；GitHub Foundations 与基础知识相契合。

技能数据： 重点学习分支管理、撤销操作（reset/restore/revert）、merge 与 rebase 的区别、远程工作流以及安全事项（不强制推送、不提交机密）。

钩子与工作流

建议的钩子： Pre-commit：运行 commit-validator（规范化提交）。Pre-push：运行测试（参考 tdd / verification-before-completion）。Post-merge：可选更新记忆/经验。

工作流： 与 developer（主要）和 devops（始终）配合使用。流程：创建分支 → 编辑 → 添加 → 验证提交消息 → 提交 → 推送；使用 github-ops 或 github-mcp 创建 PR。查看 .claude/workflows 中使用 git-expert 的功能开发和代码审查工作流。

⚡ 节省令牌的工作流

不要反复运行 git status。请使用以下工作流：

1. 检查状态：git status -s（简短格式可节省令牌）
2. 查看差异：git diff --cached（只检查即将提交的内容）
3. 查看日志：git log --oneline -5（了解上下文，不受冗余信息干扰）

🔄 常见模式

安全提交

git add <file>
git diff --cached # REVIEW THIS!
git commit -m "feat: description"

撤销上次提交（软重置）

git reset --soft HEAD~1

解决合并冲突

1. 运行 git status 查看冲突文件。
2. 编辑文件以解决冲突标记（<<<<、====、>>>>）。
3. 运行 git add <file>
4. 运行 git commit --no-edit

铁律

1. 绝不要在共享分支上使用 git push --force — 强制推送会重写所有协作者的历史记录，导致提交丢失，并在不知不觉中破坏进行中的变基；确有必要时，请使用 --force-with-lease。
2. 绝不要将机密、凭据或令牌提交到仓库 — 一旦推送，即使从 HEAD 删除，机密仍会永远存在于所有分支副本和克隆中。
3. 务必在推送到共享分支之前运行测试套件并确认通过 — 共享分支中的损坏代码会阻碍所有人，并触发紧急回滚。
4. 务必在合并前将功能分支变基到基础分支上 — 基础分支过时会造成本可避免的冲突，并在共享历史记录中产生冗杂的合并提交。
5. 绝不要对已推送到共享远程仓库的提交进行变基或重写历史 — 队友的本地分支会发生分叉，并在下次拉取时产生重复提交。

反模式

反模式	失败原因	正确做法
在共享分支上使用 git push --force	覆盖队友的提交；破坏进行中的变基分支	仅对个人分支使用 --force-with-lease；绝不在 main/develop 上使用
提交 .env 或凭据	即使删除后，也会永久保留在历史记录中；需要轮换密钥	将敏感文件添加到 .gitignore；使用提交前的密钥扫描钩子
长期存在的功能分支（>5 天）	大量合并冲突；太晚才发现集成错误	使用短期分支，每天变基到 main（主干开发）
使用 git commit -m "fix" 或 wip 消息	导致 git log 无法用于二分查找和生成变更日志	使用约定式提交：fix: resolve null pointer in user auth
未拉取最新基线就合并	合并基线过时；CI 只能在合并完成后发现冲突	进行任何合并或 PR 前，先运行 git fetch && git rebase origin/main

Git 2.45–2.50 的功能（2024–2025）

Reftable 后端（Git 2.45+）

Reftable 后端以一种更快速、原子化且更节省存储空间的二进制格式，完全取代了旧版 files 引用格式：

优点：

• 原子化的多引用更新（全有或全无的事务）
• 更快速的单引用查找和引用范围遍历
• 一致的读取——绝不会读取到部分更新状态
• 更高效地存储 reflog

为新仓库启用：

git init --ref-format=reftable my-repo

检查当前后端：

git rev-parse --show-ref-format
# outputs: files  OR  reftable

迁移说明： 将现有仓库从 files 转换为 reftable，需要重新克隆，或使用 git clone --ref-format=reftable。使用 files 仓库的客户端不受影响——后端仅用于服务端/本地。

增量多包索引（Git 2.47+）

多包索引（MIDX）允许 Git 在多个包文件之间维护单个索引，而无需重新打包。Git 2.47 新增了增量 MIDX 更新——只为新添加的包建立索引，而不必重建整个 MIDX：

# Generate or update multi-pack index
git multi-pack-index write --stdin-packs

# Verify the MIDX
git multi-pack-index verify

# Enable via maintenance
git maintenance start

多包可达性位图为 MIDX 添加了预先计算的可达性数据，大幅加快大型仓库中的 git clone、git fetch 和垃圾回收。

单体仓库的稀疏检出（Git 2.25+ 锥形模式）

稀疏检出让你只检出大型单体仓库中所需的目录：

# Clone without checking out any files
git clone --no-checkout --filter=blob:none https://github.com/org/monorepo.git
cd monorepo

# Initialize in cone mode (recommended — uses fast prefix matching)
git sparse-checkout init --cone

# Check out only specific directories
git sparse-checkout set frontend docs shared/utils

# See what is currently checked out
git sparse-checkout list

# Add more directories without losing current ones
git sparse-checkout add backend/api

# Disable sparse checkout (restore full working tree)
git sparse-checkout disable

一条命令完成克隆（Git 2.25+）：

git clone --filter=blob:none --sparse https://github.com/org/monorepo.git
cd monorepo
git sparse-checkout set services/payments

锥形模式与非锥形模式：

模式	模式匹配	性能
锥形（推荐）	仅匹配目录前缀	快（路径匹配为 O(log n)）
非锥形	完整的 gitignore 风格模式	在大型目录树上较慢

Git Scalar — 大型仓库优化

Scalar 是 Git 随附的仓库管理工具（自 Git 2.38 起提供），可自动配置并维护所有推荐的性能设置：

# Clone a large repo with all performance features enabled
scalar clone https://github.com/org/large-monorepo.git

# Register an existing repo with Scalar
scalar register

# Run all maintenance tasks manually
scalar run all

# View configured enlistments
scalar list

Scalar 自动配置的内容：

• 部分克隆（--filter=blob:none）
• 稀疏检出（锥形模式）
• 文件系统监视器（core.fsmonitor）
• 提交图生成
• 后台维护（每小时 fetch，每天 gc）
• 多包索引

使用 SSH 密钥签署提交（Git 2.34+）

SSH 密钥签名比 GPG 更简单，而且可以使用已有的身份验证密钥：

# Configure SSH signing globally
git config --global gpg.format ssh
git config --global user.signingKey ~/.ssh/id_ed25519.pub

# Sign all commits automatically
git config --global commit.gpgSign true

# Or sign a single commit manually
git commit -S -m "feat: add payment service"

# Verify a commit
git verify-commit HEAD

设置 allowed-signers 文件以供团队验证：

# ~/.config/git/allowed_signers
[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
[email protected]   ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
git log --show-signature

**GitHub 验证：**在 GitHub 的 Settings > SSH and GPG keys > New SSH key > Signing Key 下添加你的 SSH 签名密钥。使用该密钥签署的提交会在 GitHub 上显示“Verified”。

FIDO2 / 硬件安全密钥签名：

# Generate a resident key on a FIDO2 security key (e.g., YubiKey)
ssh-keygen -t ed25519-sk -O resident -f ~/.ssh/id_ed25519_sk_fido2
git config --global user.signingKey ~/.ssh/id_ed25519_sk_fido2.pub

改进的合并策略（Git 2.38+ ort）

ort 合并策略自 Git 2.34 起一直是默认策略。对于大型树，它比 recursive 快得多，也更具确定性：

# ort is the default; explicitly select if needed
git merge -s ort feature/my-feature

# Rename detection threshold (default 50%)
git merge -X rename-threshold=80 feature/rename-heavy-branch

# Conflict style: diff3 (shows common ancestor) — strongly recommended
git config --global merge.conflictStyle diff3
# Or zdiff3 (even cleaner context in conflicts, Git 2.35+)
git config --global merge.conflictStyle zdiff3

大型仓库的性能命令

# Enable file system monitor (avoids scanning entire tree for status)
git config core.fsmonitor true
git config core.untrackedCache true

# Precompute commit graph for faster log/blame
git commit-graph write --reachable --changed-paths
git config fetch.writeCommitGraph true

# Partial clone — skip large blobs on clone, fetch on demand
git clone --filter=blob:none <url>

# Shallow clone (CI use case — last N commits only)
git clone --depth=1 <url>

# Check repository health and performance
GIT_TRACE_PERFORMANCE=1 git status

相关技能

• gitflow - 分支工作流模式（feature、release、hotfix 分支）

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设会发生中断：如果没有记录在记忆中，就说明这件事没有发生。