mastering-git-cli

Git CLI 技能（2025 版）

面向现代开发的生产就绪型 Git 工作流与自动化。

兼容性： 建议使用 Git 2.38+。完整支持 SHA-256/Reftable 需要 Git 2.51+。

触发条件

此技能适用于：

• git 命令和版本控制问题
• 合并冲突、变基操作、cherry-pick 决策
• Worktree 设置和子模块管理
• 分支策略和仓库故障排查
• 大型仓库优化（Scalar、稀疏检出、无 blob 克隆）
• CI/CD 中的 Git 集成和性能调优

快速开始

最常用模式

# Clone and start working (use switch, not checkout)
git clone <url> && cd <repo>
git switch -c feature-x

# Commit workflow
git add -A && git commit -m "feat: description"
git push -u origin feature-x

# Merge feature to main
git switch main && git pull
git merge --no-ff feature-x
git push

# Large repo? Use partial clone
git clone --filter=blob:none <url>

现代 Git 配置（2025 默认值）

# Core workflow
git config --global pull.rebase true
git config --global push.autoSetupRemote true
git config --global merge.conflictStyle zdiff3
git config --global diff.algorithm histogram
git config --global rerere.enabled true
git config --global rebase.autoStash true

# Performance (essential for large repos)
git config --global core.fsmonitor true
git config --global fetch.prune true
git config --global feature.manyFiles true

# SSH signing (simpler than GPG)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# Enable background maintenance
git maintenance start

决策树

合并 vs 变基 vs cherry-pick

Need to integrate changes?
│
├─ All commits from a branch?
│  ├─ Shared branch (pushed/collaborative) → MERGE
│  └─ Local-only branch → REBASE (cleaner) or MERGE
│
└─ Specific commits only?
   └─ CHERRY-PICK
      ├─ Hotfix to release branch → cherry-pick -x
      └─ Backport to old version → cherry-pick -x

⚠️ AVOID: Rebasing shared/pushed branches (rewrites history others depend on)

Worktree vs 分支 vs 暂存

Need to switch context?
│
├─ Quick switch, will return soon → STASH
├─ Parallel work on same files → Not possible
├─ Parallel work on different features?
│  ├─ Short-lived (minutes) → STASH or COMMIT WIP
│  └─ Long-running or parallel builds → WORKTREE
│
└─ Multiple agents working simultaneously → WORKTREE (essential)

子模块 vs 子树 vs 单体仓库

External code dependency?
│
├─ Need to modify and contribute back → SUBMODULE
├─ Just embedding, no upstream → SUBTREE
├─ Tight coupling, single team → MONOREPO
└─ Standard library/package → PACKAGE MANAGER

Reset vs Revert vs Restore

Undo something?
│
├─ Discard file changes (not staged) → git restore <file>
├─ Unstage files → git restore --staged <file>
├─ Undo commits (not pushed)?
│  ├─ Keep changes staged → git reset --soft HEAD~1
│  ├─ Keep changes unstaged → git reset HEAD~1
│  └─ Discard everything → git reset --hard HEAD~1
│
└─ Undo commits (already pushed) → git revert <sha>

克隆策略（大型仓库）

How to clone?
│
├─ Small repo (<500MB) → Full clone (default)
├─ Large repo, developer workstation
│  └─ BLOBLESS clone → git clone --filter=blob:none <url>
├─ Large repo, CI build
│  ├─ Need only HEAD → SHALLOW → git clone --depth 1
│  └─ Need history → TREELESS → git clone --filter=tree:0
│
└─ Monorepo, specific directories only
   └─ SCALAR + SPARSE → scalar clone <url>, then sparse-checkout

⚠️ AVOID: Shallow clone for development (breaks blame, log, push)

checkout vs switch/restore

Which command?
│
├─ Changing branches → git switch <branch>
├─ Creating branch → git switch -c <new-branch>
├─ Discarding file changes → git restore <file>
├─ Unstaging files → git restore --staged <file>
│
└─ git checkout → Legacy (avoid in new scripts)

轻松合并

将功能分支合并到 main

git checkout main
git merge --no-ff feature    # Always creates merge commit

使用最新的 main 更新功能分支

git checkout feature
git merge main               # Safe for shared branches
# OR
git rebase main              # Only if branch not shared

使用对方版本解决所有冲突

git checkout --theirs .
git add .
git commit

使用我方版本解决所有冲突

git checkout --ours .
git add .
git commit

中止出错的合并

git merge --abort

撤销已推送的合并

git revert -m 1 <merge-sha>
git push

一次合并多个分支

git merge feature-a feature-b feature-c  # Octopus merge (no conflicts allowed)

脚本用法

Agent Worktree 设置

为并行 Agent 开发创建隔离的 worktree：

scripts/setup-agent-worktrees.sh [num_agents] [base_branch]
# Example: scripts/setup-agent-worktrees.sh 3 main
# Creates: ../agent-1, ../agent-2, ../agent-3, ../integration
# Output: "Created 3 agent worktrees from main"

使用场景： 同时运行 3 个 Claude Agent，分别开发不同功能，每个 Agent 都有独立的工作目录。

Agent Worktree 清理

移除所有 Agent worktree，并可选择删除分支：

scripts/cleanup-agent-worktrees.sh [--delete-branches] [--force]
# Example: scripts/cleanup-agent-worktrees.sh --delete-branches
# Removes worktrees and their associated branches

子模块状态报告

获取所有子模块的易读状态：

scripts/submodule-report.sh
# Output: Table showing submodule path, branch, commit, and sync status

Git 健康检查

诊断常见仓库问题：

scripts/git-health-check.sh [--verbose]
# Checks: dangling objects, broken refs, large files, stale branches

参考导航

根据任务阅读相应的参考文件：

任务	参考文件
了解 Git 内部机制、对象模型、DAG	references/foundations.md
配置 Git，设置 2025 年默认值	references/foundations.md
克隆、提交、日志和分支基础	references/daily-usage.md
创建和管理 worktree	references/worktrees.md
设置并行 Agent 工作流	references/worktrees.md
选择合并策略	references/merge-operations.md
解决合并冲突	references/merge-operations.md
使用 rerere 解决冲突	references/merge-operations.md
添加、更新和管理子模块	references/submodules.md
多仓库项目架构	references/submodules.md
reset、revert、restore 操作	references/advanced-operations.md
交互式 rebase、压缩提交	references/advanced-operations.md
储藏、标签、钩子	references/advanced-operations.md
恢复丢失的提交和分支	references/recovery.md
排查常见错误	references/recovery.md
命令速查表	references/recovery.md
SHA-256、Reftable、SSH 签名	references/git-2025-features.md
git switch/restore、range-diff	references/git-2025-features.md
Git 维护、bisect run	references/git-2025-features.md
合并队列、pre-commit 框架	references/git-2025-features.md
部分克隆/无 blob 克隆、Scalar	references/large-repos.md
单体仓库的稀疏检出	references/large-repos.md
裸仓库 + worktree 布局	references/large-repos.md
CI/CD Git 优化	references/large-repos.md

重要知识

-X ours 与 -s ours 的陷阱

# -X ours: Prefer our changes ONLY IN CONFLICTS
git merge -X ours feature
# ↑ Merges all non-conflicting changes from feature

# -s ours: IGNORE EVERYTHING from other branch
git merge -s ours feature
# ↑ Keeps our tree exactly, just records the merge

冲突样式建议

git config --global merge.conflictStyle zdiff3

在冲突中显示基准版本，让解决冲突更清晰：

<<<<<<< HEAD
our version
||||||| merged common ancestor
original version
=======
their version
>>>>>>> feature

一个分支只能存在于一个 worktree 中

一个分支只能在一个 worktree 中检出。若要在其他位置处理该分支：

git worktree add -b feature-copy ../feature-copy feature  # Create copy

子模块默认处于分离 HEAD 状态

执行 git submodule update 后，进行更改前务必先检出一个分支：

cd submodule-dir
git checkout main  # Then make changes

2025 年轻松上手

自动查找引入 bug 的提交

# Create test script: exit 0 = good, exit 1 = bad
echo '#!/bin/bash
npm test -- --grep="broken feature"' > test.sh
chmod +x test.sh

git bisect start HEAD v1.0.0
git bisect run ./test.sh
git bisect reset

比较 rebase 后的 PR（实际发生的更改）

git range-diff main..feature@{1} main..feature

单体仓库：只检出所需内容

git clone --filter=blob:none <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set backend/api frontend/app

设置性能优化

scalar register                 # Enable all optimizations
# OR manually:
git maintenance start          # Background maintenance
git config core.fsmonitor true # Filesystem watcher

SSH 签名设置（比 GPG 更简单）

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

迁移到 reftable（分支数超过 10K）

git refs migrate --ref-format=reftable

反模式（请避免）

不要使用 checkout 执行文件操作

# Bad: ambiguous, can lose data
git checkout file.txt

# Good: explicit intent
git restore file.txt

不要在开发时使用浅克隆

# Bad: breaks blame, log, push
git clone --depth 1 <url>

# Good: blobless preserves history
git clone --filter=blob:none <url>

不要省略 --force-with-lease

# Bad: can overwrite teammates' work
git push --force

# Good: fails if remote has new commits
git push --force-with-lease

不要手动运行 git gc

# Bad: blocks, runs everything at once
git gc

# Good: scheduled, incremental
git maintenance start

不要对共享分支进行 rebase

# Bad: rewrites history others depend on
git rebase main  # on a pushed branch

# Good: merge instead for shared branches
git merge main

不要提交机密或生成文件

# Bad: committing sensitive or generated files
git add .env node_modules/

# Good: ensure .gitignore is set first
echo -e ".env\nnode_modules/" >> .gitignore
git add .gitignore

不要忽略合并冲突

# Bad: accepting all changes blindly
git checkout --theirs .  # without reviewing

# Good: review each conflict
git mergetool  # or manual review with zdiff3