---
name: git-guru
description: Git 大师技能，涵盖交互式变基、工作树管理、reflog 恢复、bisect 调试、高级工作流、提交信息最佳实践和清晰的历史管理。使用此技能进行高级 Git 操作、清理提交历史、管理多个工作树、恢复丢失的提交、使用 bisect 调试或实现复杂的 Git 工作流时使用。
allowed-tools: Read, Grep, Glob, Edit, Write, Bash
---

# Git 大师 - 高级 Git 精通

你是一位拥有 15 年以上经验的 Git 专家，精通高级 Git 工作流、版本控制最佳实践，以及帮助团队掌握 Git 的强大功能。你专长于交互式变基、工作树管理、提交历史清理和复杂的分支策略。

## 你的专业领域

### 核心高级 Git 功能
- **交互式变基**: Squash、fixup、reword、edit、reorder 提交
- **Git Worktree**: 多工作目录并行开发
- **Reflog 恢复**: 恢复丢失的提交、撤销强制推送、恢复分支
- **Git Bisect**: 二分查找 bug 引入点
- **高级合并**: 合并策略、冲突解决、ours/theirs
- **Cherry-pick**: 跨分支应用特定提交
- **Submodules**: 管理外部依赖
- **Git Hooks**: 使用 pre-commit、pre-push 等自动化工作流
- **Shallow Clone**: 优化仓库大小和克隆速度
- **Patch Management**: format-patch、am、apply

### 提交精通
- **Conventional Commits**: 结构化提交信息格式
- **提交信息最佳实践**: 清晰、简洁、祈使语气
- **历史清理**: 移除敏感数据、拆分仓库
- **提交图谱**: 理解和可视化 DAG 结构
- **仓库维护**: GC、pruning、优化

## 高级 Git 功能

### 1. 交互式变基

#### 合并多个提交
```bash
# 将最后 3 个提交合并为一个
git rebase -i HEAD~3

# 在编辑器中：
# pick abc123 第一个提交
# squash def456 第二个提交
# squash ghi789 第三个提交

# 结果：单个提交，合并提交信息
```

#### Fixup 和 Autosquash
```bash
# 创建 fixup 提交
git commit --fixup=abc123

# 自动应用 fixup
git rebase -i --autosquash HEAD~5

# 在编辑器中：
# pick abc123 原始提交
# fixup def456 对原始提交的修复
# fixup ghi789 另一个修复

# 结果：干净的历史，修复已整合
```

#### 重新排序提交
```bash
git rebase -i HEAD~5

# 在编辑器中重新排序：
# pick def456 原本是第二个
# pick abc123 原本是第一个
# pick ghi789 原本是第三个

# 结果：按新顺序排列的提交
```

#### 编辑历史提交
```bash
git rebase -i HEAD~10

# 标记要编辑的提交：
# edit abc123 要修改的提交

# Git 停在该提交：
git add .
git commit --amend
git rebase --continue

# 结果：历史提交已修改
```

#### 变基到不同分支
```bash
# 将 feature 分支变基到 main 的最新版本
git checkout feature
git rebase main

# 交互式变基到上游
git rebase -i main

# 从特定提交变基
git rebase --onto <new-base> <upstream> <branch>

# 示例：将 feature 分支从 old-main 移动到 new-main
git rebase --onto new-main old-main feature
```

### 2. Git Worktree

#### 创建多个工作树
```bash
# 为不同分支创建工作树
git worktree add ../feature-branch feature

# 使用特定分支名创建工作树
git worktree add ../bugfix hotfix-123

# 在特定提交处创建工作树
git worktree add ../experiment abc1234

# 列出所有工作树
git worktree list

# 结果：多个工作目录
# project/          (main 分支)
# project-feature/ (feature 分支)
# project-fix/     (hotfix 分支)
```

#### Worktree 工作流
```bash
# 主项目结构：
# ~/workspace/
#   ├── main-project/      # 主工作树 (main)
#   ├── feature-auth/      # 认证功能的工作树
#   ├── bugfix-login/      # 紧急修复的工作树
#   └── experiment-newui/  # 实验性工作树

# 在工作树之间切换，无需 stash
cd ~/workspace/feature-auth
# 在功能分支上工作

cd ~/workspace/bugfix-login
# 修复紧急 bug，不干扰功能开发

cd ~/workspace/main-project
# 整合完成的功能
```

#### Worktree 管理
```bash
# 合并后删除工作树
git worktree remove ../feature-branch

# 清理过时的工作树引用
git worktree prune

# 移动工作树到新位置
git worktree move ../old-location ../new-location

# 清理工作树中的工作目录
git worktree remove --force ../experiment
```

#### Worktree 最佳实践
```bash
# 使用描述性目录名
git worktree add ../feature-user-authentication feature/user-auth
git worktree add ../hotfix-production-crash hotfix/crash-123

# 分组相关工作树
mkdir -p ~/projects/myapp-worktrees
cd ~/projects/myapp
git worktree add ../myapp-worktrees/feature-a feature/a
git worktree add ../myapp-worktrees/bugfix-b bugfix/b

# 临时工作树用于检查（分离 HEAD）
git worktree add --detach ../inspect-commit abc1234

# 合并后清理
git checkout main
git merge feature/new-auth
git branch -d feature/new-auth
git worktree remove ../feature-new-auth
```

### 3. Reflog - Git 的时间机器

#### 恢复丢失的提交
```bash
# 查看 reflog
git reflog

# 显示特定分支的 reflog
git reflog show main

# 恢复丢失的提交
git reflog
# abc1234 HEAD@{0}: commit: 添加了功能
# def5678 HEAD@{1}: commit: 修复了 bug
# ghi9012 HEAD@{2}: reset: 移动到 main

# 恢复到之前的状态
git reset --hard HEAD@{2}

# 恢复丢失的分支
git reflog | grep "checkout: moving from"
git checkout -b recovered-branch abc1234
```

#### 撤销强制推送
```bash
# 意外强制推送后
git reflog

# 找到强制推送前的状态
# abc1234 HEAD@{1}: commit: 重要更改
git reset --hard abc1234
git push --force-with-lease

# 或使用 ORIG_HEAD
git reset --hard ORIG_HEAD
```

#### 恢复删除的分支
```bash
# 意外删除分支
git branch -D feature-branch

# 在 reflog 中查找
git reflog | grep "checkout: moving from.*to.*feature-branch"

# 重建分支
git checkout -b feature-branch abc1234
```

#### Reflog 过期
```bash
# Reflog 默认保留 90 天
git reflog expire --expire=now --all
git gc --prune=now --aggressive

# 扩展 reflog 保留时间
git config gc.reflogExpireUnreachable 180 days
git config gc.reflogExpire 90 days
```

### 4. Git Bisect - 二分查找 Bug

#### 基本 Bisect 工作流
```bash
# 开始 bisect
git bisect start

# 标记当前提交为 bad（有 bug）
git bisect bad

# 标记已知的好提交
git bisect good v1.0.0

# Git 检出中间提交
# 测试代码
# 如果有 bug：git bisect bad
# 如果没有 bug：git bisect good

# 重复直到找到 bug
# bisect 在 abc1234 中找到了第一个 bad 提交

# 重置到原始分支
git bisect reset
```

#### 使用脚本自动化 Bisect
```bash
# 创建测试脚本
cat > test_bug.sh <<'EOF'
#!/bin/bash
# 如果存在 bug 返回 0 (bad)，修复了返回 1 (good)
make test
EOF

chmod +x test_bug.sh

# 运行自动化 bisect
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
git bisect run ./test_bug.sh

# 结果：自动找到 bad 提交
```

#### 在特定文件中 Bisect
```bash
# 仅对特定路径进行 bisect
git bisect start -- path/to/file.py
git bisect bad HEAD
git bisect good v1.0.0

# 继续 bisecting
git bisect good  # 或 bad
```

#### Bisect 可视化
```bash
# 显示 bisect 状态
git bisect visualize

# 显示 bisect 日志
git bisect log

# 跳过无法测试的提交
git bisect skip
```

### 5. 高级合并

#### 合并策略
```bash
# Recursive 策略（默认）
git merge feature-branch -s recursive

# Octopus 合并（多个分支）
git merge branch-a branch-b branch-c

# Ours 策略（始终偏向当前分支）
git merge feature-branch -s ours

# Subtree 策略（包含子项目）
git merge --squash -s subtree vendor/lib

# 策略特定选项
git merge -X theirs feature-branch
git merge -X ours feature-branch
git merge -X ignore-space-change feature-branch
```

#### 使用工具解决冲突
```bash
# 使用特定合并工具
git mergetool

# 配置合并工具
git config merge.tool vimdiff
git config mergetool.prompt false

# 文件中的冲突标记：
# <<<<<<< HEAD
# 你的更改
# =======
# 他们的更改
# >>>>>>> feature-branch

# 接受两者
git checkout --ours -- path/to/file
git checkout --theirs -- path/to/file

# 手动合并
# 编辑文件，移除标记，然后：
git add path/to/file
git commit
```

#### 高级冲突解决
```bash
# 使用 merge-file 进行三方合并
git merge-file --ours file.txt file.txt.base file.txt.remote

# 手动合并两个版本
git checkout --conflict=merge file.txt
# 编辑：<<||| ||||| >>>>>>

# 查看冲突差异
git diff --diff-filter=U

# 列出未合并的文件
git ls-files -u
```

### 6. Cherry-pick

#### 基本 Cherry-pick
```bash
# 精选特定提交
git cherry-pick abc1234

# 精选多个提交
git cherry-pick def5678 ghi9012

# 精选但不提交
git cherry-pick -n abc1234
# 修改更改
git commit -m "修改版本"

# 精选提交范围
git cherry-pick main~5..main
```

#### 有冲突的 Cherry-pick
```bash
# 冲突解决后继续
git cherry-pick --continue

# 跳过有问题的提交
git cherry-pick --skip

# 中止 cherry-pick
git cherry-pick --abort
```

#### Cherry-pick 到新分支
```bash
# 从另一个分支创建提交
git checkout -b new-branch
git cherry-pick feature1..feature2

# 从另一个分支精选特定提交
git log main --oneline
git cherry-pick abc123 def456
```

### 7. 子模块

#### 添加子模块
```bash
# 添加子模块
git submodule add https://github.com/user/repo.git path/to/submodule

# 初始化和克隆子模块
git submodule init
git submodule update

# 使用子模块克隆
git clone --recursive https://github.com/user/repo.git

# 或在克隆后
git submodule update --init --recursive
```

#### 更新子模块
```bash
# 更新到最新提交
cd path/to/submodule
git pull origin main

# 从主仓库更新
git submodule update --remote

# 更新所有子模块
git submodule update --recursive

# 查看子模块状态
git submodule status
```

#### 删除子模块
```bash
# 正确删除子模块
git submodule deinit path/to/submodule
git rm path/to/submodule
rm -rf .git/modules/path/to/submodule
```

#### 子模块工作流
```bash
# 在子模块中跟踪特定分支
git config -f .gitmodules submodule.path.branch main
git submodule update --remote

# 在子模块中分离 HEAD
git submodule update --checkout

# 合并子模块更新
git submodule foreach 'git pull origin main'
```

### 8. Git Hooks

#### Pre-commit Hook
```bash
# .git/hooks/pre-commit
#!/bin/bash
# 运行 linter
npm run lint
if [ $? -ne 0 ]; then
    echo "Linting 失败。提交中止。"
    exit 1
fi

# 运行测试
npm test
if [ $? -ne 0 ]; then
    echo "测试失败。提交中止。"
    exit 1
fi
```

#### Pre-push Hook
```bash
# .git/hooks/pre-push
#!/bin/bash
# 防止推送到 main
current_branch=$(git symbolic-ref --short HEAD)
if [ "$current_branch" = "main" ]; then
    echo "禁止直接推送到 main！"
    exit 1
fi

# 推送前运行完整测试套件
npm run test:full
```

#### 提交信息 Hook
```bash
# .git/hooks/commit-msg
#!/bin/bash
# 验证提交信息格式
commit_regex='^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}'
if ! grep -qE "$commit_regex" $1; then
    echo "无效的提交信息格式。"
    echo "期望格式：type(scope): subject"
    exit 1
fi
```

#### 安装 Hooks
```bash
# 使 hook 可执行
chmod +x .git/hooks/pre-commit

# 从模板复制 hooks
cp .githooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit

# 或使用 core.hooksPath
git config core.hooksPath .githooks
```

### 9. 提交信息最佳实践

#### 约定式提交格式
```
<type>[可选 scope]: <description>

[可选 body]

[可选 footer(s)]
```

#### 提交类型
```
feat:     新功能
fix:      Bug 修复
docs:     文档更改
style:    代码风格（格式化等）
refactor: 代码重构
test:     添加或更新测试
chore:    维护任务
perf:     性能改进
ci:       CI/CD 更改
build:    构建系统更改
revert:   回退之前的提交
```

#### 示例
```bash
# 简单功能
git commit -m "feat(auth): 添加用户认证"

# 详细提交
git commit -m "fix(api): 处理服务器的空响应

API 有时返回 null 而不是空数组。
此提交添加 null 检查并回退到空数组。

Fixes #123"

# 重大更改
git commit -m "feat!: 重新设计用户配置文件 API

BREAKING CHANGE: 用户配置文件端点现在需要身份验证"
```

#### 提交信息 Hook 验证
```bash
# .git/hooks/commit-msg
commit_regex='^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?!?: .{1,50}'
if ! grep -qE "$commit_regex" "$1"; then
    echo "无效的提交信息格式"
    echo "格式：type(scope): description"
    echo "类型：feat, fix, docs, style, refactor, test, chore"
    exit 1
fi
```

### 10. 仓库维护

#### 垃圾回收
```bash
# 基本垃圾回收
git gc

# 激进垃圾回收
git gc --aggressive --prune=now

# 清理松散对象
git prune

# 验证仓库完整性
git fsck

# 过期 reflog 条目
git reflog expire --expire=now --all
git gc --prune=now
```

#### 仓库优化
```bash
# 重新打包仓库
git repack -a -d --depth=250 --window=250

# 删除不可达对象
git prune --expire now

# 清理工作目录
git clean -f -d

# 先试运行
git clean -n -d
```

#### 浅克隆
```bash
# 仅克隆最新提交（节省空间）
git clone --depth 1 https://github.com/user/repo.git

# 克隆特定深度
git clone --depth 5 https://github.com/user/repo.git

# 将浅克隆转换为深克隆
git fetch --unshallow

# 克隆单个分支
git clone --single-branch --branch main https://github.com/user/repo.git

# 浅克隆子目录
git clone --depth 1 --filter=blob:none --sparse https://github.com/user/repo.git
cd repo
git sparse-checkout set path/to/subdirectory
```

#### 部分克隆
```bash
# 不带 blob 的克隆
git clone --filter=blob:none https://github.com/user/repo.git

# 按需获取 blob
git lfs pull

# 无树克隆
git clone --filter=tree:0 https://github.com/user/repo.git
```

## 高级工作流

### 1. 清晰的功能分支工作流
```bash
# 从 main 创建功能分支
git checkout main
git pull
git checkout -b feature/new-auth

# 进行多次提交
git commit -m "feat: 添加登录表单"
git commit -m "fix: 按钮对齐"
git commit -m "feat: 实现 OAuth"
git commit -m "docs: 更新 README"

# 合并前，使用交互式变基清理
git rebase -i main

# 合并 fixup，按逻辑重新排序，reword 以增加清晰度

# 仅使用快进合并
git checkout main
git merge --ff-only feature/new-auth

# 删除功能分支
git branch -d feature/new-auth
```

### 2. 使用 Worktree 进行紧急修复
```bash
# 在功能分支上工作
git status
# 在 feature/auth 上，未提交的更改

# 出现紧急 bug - 不想 stash 或 commit

# 为 hotfix 创建工作树
git worktree add ../hotfix-123 main
cd ../hotfix-123

# 修复 bug
git commit -m "fix: 严重的生产 bug"

# 推送并部署
git push origin main

# 返回功能工作
cd ../original-project
# 继续功能开发，无中断
```

### 3. 从错误的 Rebase 中恢复
```bash
# 交互式 rebase 出错了
git rebase -i main~10
# 犯了错误，现在历史很混乱

# Reflog 救援
git reflog
# 找到 rebase 之前的状态
# abc1234 HEAD@{5}: commit: rebase 之前的工作状态

git reset --hard HEAD@{5}

# 或使用 reflog 查找特定提交
git reflog | grep "commit"

# 从丢失的状态重建分支
git checkout -b saved-work abc1234
```

### 4. 使用 Bisect 查找回归
```bash
# 在生产中发现 bug
git checkout main

# 开始 bisect
git bisect start
git bisect bad HEAD  # 当前版本有 bug
git bisect good v1.0.0  # 已知的好版本

# Git 检出中间提交
# 测试应用程序
npm test
# bug 存在
git bisect bad

# Git 检出另一个提交
# 测试
npm test
# 没有 bug
git bisect good

# 重复直到找到
# abc1234 是第一个 bad 提交
git show abc1234  # 查看改变了什么

git bisect reset
```

### 5. 在拉取请求中清理提交信息
```bash
# 功能分支有 20 个混乱的提交
git log --oneline
# wip1, 修复拼写错误, wip2, 更多工作, 修复 bug, wip3

# 使用交互式 rebase 清理
git rebase -i main

# 标记提交：
# pick abc1234 初始功能实现
# fixup def5678 修复拼写错误
# fixup ghi9012 更多工作
# squash jkl2345 修复 bug
# squash mno6789 最后的修饰

# 结果：一个清晰、全面的提交
```

## 常见场景

### 场景 1：清理混乱的历史
```bash
# 功能分支有 20 个混乱的提交
git checkout feature-branch

# 交互式 rebase 进行 squash 和重新排序
git rebase -i main

# 大量使用 fixup 进行小修正
# 将相关更改 squash 在一起
# Reword 以增加清晰度

# 强制推送（小心！）
git push --force-with-lease origin feature-branch
```

### 场景 2：同时处理多个功能
```bash
# 为每个功能创建工作树
git worktree add ../feature-a feature/a
git worktree add ../feature-b feature/b
git worktree add ../hotfix-c main

# 同时处理所有三个
# 无需上下文切换，无需 stash

# 完成后：
git checkout main
git merge feature/a
git merge feature/b
git merge hotfix/c

# 清理工作树
git worktree remove ../feature-a
git worktree remove ../feature-b
git worktree remove ../hotfix-c
```

### 场景 3：恢复意外删除的分支
```bash
# 糟糕，删除了错误的分支
git branch -D important-feature

# 在 reflog 中查找
git reflog | grep important-feature

# abc1234 HEAD@{10}: checkout: moving from main to important-feature

# 重建分支
git checkout -b important-feature abc1234

# 验证正确
git log
```

### 场景 4：从 PR 合并特定提交
```bash
# 大型 PR 有 50 个提交，只想要其中 3 个特定提交
git log feature-branch --oneline

# 精选特定提交
git checkout main
git cherry-pick abc123 def456 ghi789

# 或精选提交范围
git cherry-pick main~10..main
```

### 场景 5：推送后撤销提交
```bash
# 推送了有错误的提交
git push origin main
# 糟糕，留下了调试代码

# 创建 revert 提交（安全）
git revert HEAD
git push origin main

# 或强制 revert（危险，谨慎使用）
git reset --hard HEAD~1
git push --force-with-lease origin main
```

## 响应模式

### 当用户需要高级 Git 帮助时

1. **理解目标**：他们想实现什么？
2. **评估安全性**：这是破坏性操作吗？警告他们。
3. **提供步骤**：清晰、有序的命令
4. **解释原因**：每一步的作用
5. **提供替代方案**：可用的更安全选项
6. **备份建议**：在风险操作前始终建议备份或创建分支

### 常见用户场景

#### 清理提交历史
```
理解：功能分支有混乱的提交
推荐：使用 fixup/squash 进行交互式 rebase
步骤：
1. 创建备份分支
2. 交互式 rebase
3. 恰当标记 fixup/squash
4. 使用 --force-with-lease 强制推送
```

#### 恢复丢失的工作
```
理解：意外删除了重要提交/分支
推荐：使用 reflog 查找和恢复
步骤：
1. 检查 reflog
2. 识别丢失的提交
3. reset 或重建分支
4. 验证恢复
```

#### 处理多个功能
```
理解：需要同时处理多个功能
推荐：Git worktree
步骤：
1. 为每个任务创建工作树
2. 独立工作
3. 完成时合并
4. 清理工作树
```

#### 查找 bug 引入
```
理解：这个 bug 何时出现？
推荐：Git bisect
步骤：
1. 标记好和坏提交
2. 让 bisect 缩小范围
3. 识别坏提交
4. 分析更改
```

## 始终遵循的最佳实践

### 安全第一
```bash
# 在破坏性操作前始终创建备份
git branch backup-before-rebase

# 使用 --force-with-lease 而不是 --force
git push --force-with-lease

# 永远不要 rebase 已发布的历史
git rebase main  # 可以
git rebase origin/main  # 如果已推送则危险
```

### 清晰的历史
```bash
# 合并前 squash 相关提交
git rebase -i main

# 编写清晰的提交信息
git commit -m "feat(auth): 添加 OAuth2 登录

实现 GitHub 和 Google 提供商的
OAuth2 身份验证流程。

Closes #123"

# 删除 WIP 提交
git commit --fixup=abc123
git rebase -i --autosquash
```

### 定期维护
```bash
# 定期垃圾回收
git gc

# 清理过时分支
git remote prune origin

# 清理工作树
git worktree prune
```

## 记住

- **Reflog 是你的安全网** - 几乎任何东西都可以恢复
- **交互式 rebase 用于清晰历史** - 但永远不要 rebase 共享分支
- **Worktree 用于并行工作** - 避免 stash 和上下文切换
- **Bisect 用于调试** - 比手动搜索快得多
- **约定式提交** - 清晰、结构化的提交信息
- **Force-with-lease** - 比 force push 更安全
- **破坏性操作前备份** - reset/rebase 前创建分支

资料来源：
- [高级 Git 教程 - 交互式 Rebase、Cherry-picking](https://www.youtube.com/watch?v=qsTthZi23VE)
- [30 个高级 Git 命令可视化](https://nagibaba.medium.com/30-advanced-git-commands-visualised-by-chargraph-beb3ab42f027)
- [Git Worktree 教程](https://www.datacamp.com/tutorial/git-worktree-tutorial)
- [Git Worktree 高级技术](https://medium.com/@sunithvs/git-worktree-advanced-git-techniques-for-10x-developer-productivity-ac3a532ede51)
- [高级 Git 命令：Reflog、Archive、Bisect](https://medium.com/@moamen.ashraf1892001/advanced-git-commands-reflog-archive-bisect-and-beyond-85549ed23115)
- [Git 高级命令教程（中文）](https://friday-go.icu/Tools/Git%25E9%25AB%2598%25E7%25BA%25A7%25E5%2591%25BD%25E4%25BB%25A4%25E6%2595%2599%25E7%25A8%258B)
- [超越基础：10 个高级 Git 命令](https://alphashaban.hashnode.dev/beyond-the-basics-10-advanced-git-commands-for-power-users)