git-advanced

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

当激活此技能时，你的第一条回复请始终以🧢表情开头。

Git Advanced

Git高级操作

Git is a distributed version control system built on a directed acyclic graph (DAG) of immutable commit objects. Most developers use only 20% of git's power - add, commit, push, pull. The remaining 80% covers the workflows that separate a junior from a senior: precise history rewriting with interactive rebase, surgical bug hunting with bisect, parallel development with worktrees, automated quality gates with hooks, and safe history recovery with reflog. This skill equips an agent to handle any advanced git task with confidence.

Git是一个基于不可变提交对象的有向无环图（DAG）构建的分布式版本控制系统。大多数开发者只使用Git 20%的功能——add、commit、push、pull。剩下的80%则是区分初级和高级开发者的工作流：使用交互式变基精准重写提交历史、用bisect精准定位bug、用工作树实现并行开发、用钩子搭建自动化质量关卡、用引用日志安全恢复历史。此技能让Agent能够自信处理任何高级Git任务。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Wants to squash, fixup, reorder, or edit commits with interactive rebase
Needs to find the exact commit that introduced a bug (git bisect)
Wants to work on multiple branches simultaneously without stashing (worktrees)
Needs to set up pre-commit, commit-msg, or other git hooks
Wants to cherry-pick specific commits across branches
Has lost commits, stashes, or rebased away work and needs recovery
Needs to handle a complex merge conflict with diverged histories
Asks about stash management, patch workflows, or reflog navigation

Do NOT trigger this skill for:

Basic git operations (add, commit, push, pull, clone) - no skill needed
Repository hosting platform features (GitHub PRs, GitLab MRs, Bitbucket pipelines)

当用户有以下需求时触发此技能：

想要通过交互式变基合并、修正、重排或编辑提交
需要找到引入bug的具体提交（git bisect）
想要同时在多个分支上工作而无需暂存（工作树）
需要设置pre-commit、commit-msg或其他Git钩子
想要跨分支cherry-pick特定提交
丢失了提交、暂存内容，或因变基丢失工作需要恢复
需要处理历史分叉的复杂合并冲突
询问暂存管理、补丁工作流或引用日志导航相关问题

请勿在以下场景触发此技能：

基础Git操作（add、commit、push、pull、clone）——无需技能
代码托管平台功能（GitHub PRs、GitLab MRs、Bitbucket pipelines）

Key principles

核心原则

Commit often, rebase before push - Small, frequent commits preserve context and make bisect effective. Before pushing to a shared branch, use interactive rebase to clean the history into logical, reviewable units.
Never rewrite shared history - Any branch that others have checked out must not be force-pushed. Rebase and amend only on local branches or feature branches you own.
```
git push --force-with-lease
```
over
```
--force
```
if you must.
Atomic commits - Each commit should represent one logical change that leaves the codebase in a working state. An atomic commit can be reverted or cherry-picked without side effects. If your commit message needs "and", split the commit.
Branch naming conventions - Use prefixes to communicate intent:
```
feat/
```
,
```
fix/
```
,
```
chore/
```
,
```
refactor/
```
,
```
docs/
```
. Include a ticket number when applicable:
```
feat/PROJ-123-user-auth
```
. Lowercase, hyphens, no spaces.
Hooks prevent bad commits - Git hooks are the last line of defense before code enters the repository. Pre-commit hooks run linters and formatters; commit-msg hooks enforce message conventions; pre-push hooks run tests. Automate quality at the source.

频繁提交，推送前变基 - 小而频繁的提交保留上下文，让bisect更有效。推送到共享分支前，使用交互式变基将历史整理为逻辑清晰、便于评审的单元。
永远不要重写共享历史 - 任何已被其他人检出的分支都不能强制推送。仅在本地分支或你拥有的功能分支上执行变基和提交修正。如果必须强制推送，请使用
```
git push --force-with-lease
```
而非
```
--force
```
。
原子提交 - 每个提交应代表一个逻辑变更，且提交后代码库处于可工作状态。原子提交可以被回滚或cherry-pick而无副作用。如果你的提交消息需要用“和”连接内容，请拆分提交。
分支命名规范 - 使用前缀传达分支意图：
```
feat/
```
、
```
fix/
```
、
```
chore/
```
、
```
refactor/
```
、
```
docs/
```
。适用时包含工单编号：
```
feat/PROJ-123-user-auth
```
。使用小写字母、连字符，不使用空格。
钩子阻止不良提交 - Git钩子是代码进入仓库前的最后一道防线。Pre-commit钩子运行代码检查和格式化工具；commit-msg钩子强制执行提交消息规范；pre-push钩子运行测试。从源头自动化质量管控。

Core concepts

核心概念

DAG model - Git history is a directed acyclic graph where each commit points to its parent(s). A commit is identified by a SHA-1 hash of its content, parent hashes, author, and message. Branches are just named pointers to commits. Understanding the DAG explains why rebasing "moves" commits (it creates new ones) and why merge creates a commit with two parents.

Refs, HEAD, and detached HEAD -

HEAD

is a pointer to the currently checked-out commit. Normally it points to a branch ref (

refs/heads/main

), which points to a commit. "Detached HEAD" means HEAD points directly to a commit SHA, not a branch. This happens during rebase, bisect, and

git checkout <sha>

. Always create a branch before committing in detached HEAD state.

Rebase vs merge - Both integrate changes from one branch into another, but with different history shapes. Merge preserves the true history with a merge commit (two parents). Rebase replays commits on top of the target, producing a linear history but rewriting SHAs. Use merge for integrating shared branches (main, develop); use rebase to keep feature branches current and clean before merging. See

references/rebase-strategies.md

for detailed decision guidance.

Reflog as safety net - The reflog (

git reflog

) records every position HEAD has been at, including rebases, resets, and amends. It retains entries for 90 days by default. Any commit that was ever reachable is recoverable via reflog - it is the ultimate undo mechanism. Nothing is truly lost until

git gc

runs and the reflog entries expire.

DAG模型 - Git历史是一个有向无环图，每个提交指向其父提交。提交由其内容、父提交哈希、作者和消息的SHA-1哈希标识。分支只是指向提交的命名指针。理解DAG能解释为什么变基会“移动”提交（实际是创建新提交），以及为什么合并会创建一个有两个父提交的提交。

引用、HEAD与分离HEAD状态 -

HEAD

是指向当前检出提交的指针。通常它指向分支引用（如

refs/heads/main

），而分支引用指向提交。“分离HEAD状态”意味着HEAD直接指向提交SHA，而非分支。这种情况会在变基、bisect和

git checkout <sha>

时发生。在分离HEAD状态下提交前，请务必创建分支。

变基 vs 合并 - 两者都能将一个分支的变更整合到另一个分支，但历史形态不同。合并通过合并提交（两个父提交）保留真实历史。变基将提交重放到目标分支之上，产生线性历史但会重写SHA。合并适用于整合共享分支（main、develop）；变基用于在合并前保持功能分支的更新和整洁。详见

references/rebase-strategies.md

获取详细决策指南。

引用日志作为安全网 - 引用日志（

git reflog

）记录了HEAD曾经指向的所有位置，包括变基、重置和提交修正。默认保留90天的记录。任何曾经可访问的提交都可以通过引用日志恢复——它是终极撤销机制。直到

git gc

运行且引用日志条目过期，提交才会真正丢失。

Common tasks

常见任务

Interactive rebase - squash, fixup, and reorder commits

交互式变基——合并、修正和重排提交

Use interactive rebase to clean up local history before pushing. Always target a commit that is not on a shared branch.

bash

undefined

推送前使用交互式变基清理本地历史。请始终以非共享分支上的提交为目标。

bash

undefined

Rebase last N commits interactively

交互式变基最近N个提交

git rebase -i HEAD~5

Rebase all commits since branching from main

变基所有从main分支分叉后的提交

git rebase -i $(git merge-base HEAD main)


In the editor that opens, each line is a commit with an action keyword:

pick a1b2c3 feat: add login page pick d4e5f6 wip: half-done validation pick g7h8i9 fix typo pick j0k1l2 fix: complete validation logic pick m3n4o5 chore: remove console.logs


Change keywords to reshape history:
- `squash` (s) - merge into previous commit, combine messages
- `fixup` (f) - merge into previous commit, discard this message
- `reword` (r) - keep commit but edit the message
- `edit` (e) - pause rebase to amend the commit
- `drop` (d) - delete the commit entirely
- Reorder lines to reorder commits

pick a1b2c3 feat: add login page fixup g7h8i9 fix typo squash j0k1l2 fix: complete validation logic fixup d4e5f6 wip: half-done validation drop m3n4o5 chore: remove console.logs


If conflicts arise during rebase:
```bash

git rebase -i $(git merge-base HEAD main)


在打开的编辑器中，每一行是一个带有操作关键字的提交：

pick a1b2c3 feat: add login page pick d4e5f6 wip: half-done validation pick g7h8i9 fix typo pick j0k1l2 fix: complete validation logic pick m3n4o5 chore: remove console.logs


修改关键字以重塑历史：
- `squash` (s) - 合并到前一个提交，合并提交消息
- `fixup` (f) - 合并到前一个提交，丢弃当前提交消息
- `reword` (r) - 保留提交但编辑消息
- `edit` (e) - 暂停变基以修正提交
- `drop` (d) - 完全删除提交
- 重新排序行以重排提交

pick a1b2c3 feat: add login page fixup g7h8i9 fix typo squash j0k1l2 fix: complete validation logic fixup d4e5f6 wip: half-done validation drop m3n4o5 chore: remove console.logs


如果变基过程中出现冲突：
```bash

Resolve conflicts in the marked files, then:

标记文件中的冲突，然后：

git add <resolved-files> git rebase --continue

To abort and return to original state:

要中止并返回原始状态：

git rebase --abort

undefined

git rebase --abort

undefined

Git bisect to find the commit that introduced a bug

使用Git bisect查找引入bug的提交

Bisect performs a binary search through commit history to find the first bad commit. It requires you to identify one good commit and one bad commit.

bash

undefined

Bisect通过提交历史进行二分查找，找到第一个引入bug的提交。你需要指定一个正常的提交和一个有bug的提交。

bash

undefined

Start bisect session

启动bisect会话

git bisect start

Mark the current commit as bad (has the bug)

将当前标记为有bug的提交

git bisect bad

Mark a known-good commit (before the bug existed)

标记一个已知正常的提交（bug出现之前）

git bisect good v2.1.0

or by SHA:

或通过SHA：

git bisect good a1b2c3d

Git checks out the midpoint - test, then mark:

Git会检出中间提交——测试后标记：

git bisect good # if this commit does NOT have the bug git bisect bad # if this commit DOES have the bug

git bisect good # 如果此提交没有bug git bisect bad # 如果此提交有bug

Repeat until git identifies the first bad commit.

重复直到Git找到第一个有bug的提交。

When done, reset to original branch:

完成后，重置到原始分支：

git bisect reset


Automate bisect with a test script (exit 0 = good, exit 1 = bad):
```bash
git bisect start
git bisect bad HEAD
git bisect good v2.1.0
git bisect run npm test -- --testNamePattern="the failing test"
git bisect reset

git bisect reset


使用测试脚本自动化bisect（退出码0=正常，1=有bug）：
```bash
git bisect start
git bisect bad HEAD
git bisect good v2.1.0
git bisect run npm test -- --testNamePattern="the failing test"
git bisect reset

Manage worktrees for parallel work

管理工作树实现并行工作

Worktrees allow multiple working directories from a single repository, each on a different branch. No stashing needed to switch context.

bash

undefined

工作树允许从单个仓库创建多个工作目录，每个目录对应不同分支。无需暂存即可切换上下文。

bash

undefined

List existing worktrees

列出现有工作树

git worktree list

Add a new worktree for a feature branch (sibling directory)

为功能分支添加新工作树（同级目录）

git worktree add ../project-hotfix fix/PROJ-456-crash

Add a worktree for a new branch that doesn't exist yet

为尚未存在的新分支添加工作树

git worktree add -b feat/PROJ-789-search ../project-search main

Work in the worktree directory normally - all git operations are branch-specific

在工作树目录中正常工作——所有Git操作都是分支特定的

cd ../project-hotfix git log --oneline -5

Remove a worktree when done

完成后删除工作树

git worktree remove ../project-hotfix

Prune stale worktree references (if directory was manually deleted)

清理过时的工作树引用（如果目录已手动删除）

git worktree prune

undefined

git worktree prune

undefined

Set up pre-commit hooks with Husky

使用Husky设置提交前钩子

Husky manages git hooks via npm scripts, checked into the repository so all team members share the same hooks.

bash

undefined

Husky通过npm脚本管理Git钩子，钩子会被提交到仓库，以便所有团队成员共享相同的钩子配置。

bash

undefined

Install husky

安装husky

npm install --save-dev husky

Initialize husky (creates .husky/ directory and sets core.hooksPath)

初始化husky（创建.husky/目录并设置core.hooksPath）

npx husky init


Create `.husky/pre-commit`:
```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

Configure

lint-staged

package.json

json

{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,md,json}": ["prettier --write"]
  }
}

Create

.husky/commit-msg

to enforce conventional commits:

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit "$1"

bash

undefined

npx husky init


创建`.husky/pre-commit`：
```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

在

package.json

中配置

lint-staged

：

json

{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,md,json}": ["prettier --write"]
  }
}

创建

.husky/commit-msg

以强制执行规范提交：

bash

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit "$1"

bash

undefined

Install commitlint

安装commitlint

npm install --save-dev @commitlint/cli @commitlint/config-conventional

commitlint.config.js

echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

undefined

echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

undefined

Recover lost commits with reflog

使用引用日志恢复丢失的提交

The reflog records every HEAD movement. Use it when a rebase, reset, or amend discards commits you still need.

bash

undefined

引用日志记录了所有HEAD的移动。当变基、重置或提交修正丢弃了你仍需要的提交时，可以使用它。

bash

undefined

View full reflog with timestamps

查看带时间戳的完整引用日志

git reflog --date=relative

Example reflog output:

引用日志输出示例：

a1b2c3d HEAD@{0}: rebase (finish): returning to refs/heads/feat/search

d4e5f6g HEAD@{1}: rebase (pick): fix: handle empty results

e7f8g9h HEAD@{2}: rebase (start): checkout main

f0a1b2c HEAD@{3}: commit: feat: add search indexing <-- the lost commit

f0a1b2c HEAD@{3}: commit: feat: add search indexing <-- 丢失的提交

Recover by creating a branch at the lost commit SHA or reflog entry:

通过丢失提交的SHA或引用日志条目创建分支来恢复：

git checkout -b recovery/lost-search-indexing HEAD@{3}

or

或

git checkout -b recovery/lost-search-indexing f0a1b2c

Cherry-pick recovered commit onto your branch:

将恢复的提交cherry-pick到你的分支：

git checkout feat/search git cherry-pick f0a1b2c


To recover a dropped stash:
```bash

git checkout feat/search git cherry-pick f0a1b2c


恢复已丢弃的暂存：
```bash

Find dangling commits (stashes are commits)

查找悬空提交（暂存是提交对象）

git fsck --lost-found | grep commit

Inspect each dangling commit to find your stash content:

检查每个悬空提交以找到你的暂存内容：

git show <dangling-sha>

Apply the recovered stash:

应用恢复的暂存：

git stash apply <dangling-sha>

undefined

git stash apply <dangling-sha>

undefined

Cherry-pick specific commits across branches

跨分支Cherry-pick特定提交

Cherry-pick copies a commit (or range of commits) onto the current branch by replaying its diff.

bash

undefined

Cherry-pick通过重放提交的差异，将一个（或一系列）提交复制到当前分支。

bash

undefined

Cherry-pick a single commit by SHA

通过SHA cherry-pick单个提交

git cherry-pick a1b2c3d

Cherry-pick a range (inclusive on both ends)

Cherry-pick一个范围（包含两端）

git cherry-pick a1b2c3d^..f0e9d8c

Cherry-pick without immediately committing (stage only)

Cherry-pick但不立即提交（仅暂存）

git cherry-pick --no-commit a1b2c3d

If cherry-pick conflicts, resolve then:

如果cherry-pick出现冲突，解决后：

git add <resolved-files> git cherry-pick --continue

Abort cherry-pick:

中止cherry-pick：

git cherry-pick --abort


Use `-x` to annotate the cherry-picked commit message with the original SHA:
```bash
git cherry-pick -x a1b2c3d

git cherry-pick --abort


使用`-x`在cherry-pick的提交消息中添加原始SHA的注释：
```bash
git cherry-pick -x a1b2c3d

Adds "(cherry picked from commit a1b2c3d)" to the commit message

会在提交消息中添加"(cherry picked from commit a1b2c3d)"

undefined

undefined

Resolve complex merge conflicts

解决复杂合并冲突

When branches have diverged significantly, use a three-way merge tool.

bash

undefined

当分支显著分叉时，使用三方合并工具。

bash

undefined

See all conflicted files

查看所有冲突文件

git diff --name-only --diff-filter=U

Open a visual merge tool (configured via git config merge.tool)

打开可视化合并工具（通过git config merge.tool配置）

git mergetool

For a specific file, compare all three versions:

对于特定文件，比较三个版本：

git show :1:src/app.ts # common ancestor git show :2:src/app.ts # ours (current branch) git show :3:src/app.ts # theirs (incoming branch)

git show :1:src/app.ts # 共同祖先版本 git show :2:src/app.ts # 我们的版本（当前分支） git show :3:src/app.ts # 他们的版本（ incoming分支）

Accept ours or theirs entirely for a file:

完全接受我们或他们的文件版本：

git checkout --ours src/app.ts git checkout --theirs src/app.ts

After resolving all conflicts:

解决所有冲突后：

git add . git merge --continue

If the merge is unrecoverable:

如果合并无法恢复：

git merge --abort


For a long-lived feature branch, prefer rebase over merge to replay commits on
top of main one at a time - resolving smaller, isolated conflicts rather than one
massive merge conflict.

---

git merge --abort


对于长期存在的功能分支，优先使用变基而非合并，将提交逐个重放到main分支上——解决更小、孤立的冲突，而非一次性处理大规模合并冲突。

---

Error handling

错误处理

Error	Cause	Resolution
`CONFLICT (content): Merge conflict in <file>`	Two branches modified the same lines differently	Open file, resolve `<<<<<<<` markers, `git add <file>` , then `git rebase --continue` or `git merge --continue`
`error: cannot rebase: You have unstaged changes`	Working tree is dirty when starting rebase	`git stash` , rebase, then `git stash pop`
`fatal: refusing to merge unrelated histories`	Two repos with no common ancestor being merged	Use `git merge --allow-unrelated-histories` once; investigate why histories diverged
`error: failed to push some refs` after rebase	Remote has diverged (rebased shared history)	If the branch is yours alone: `git push --force-with-lease` . If shared: do not force-push, merge instead
`detached HEAD state` after bisect/checkout	HEAD points to commit SHA, not a branch	`git checkout -b <new-branch>` to save work, or `git checkout <branch-name>` to return
`Your local changes would be overwritten by checkout`	Uncommitted changes conflict with target branch	Commit or stash changes first: `git stash push -m "wip: context"` , then switch branches

错误	原因	解决方法
`CONFLICT (content): Merge conflict in <file>`	两个分支对同一行内容进行了不同修改	打开文件，解决 `<<<<<<<` 标记，执行 `git add <file>` ，然后运行 `git rebase --continue` 或 `git merge --continue`
`error: cannot rebase: You have unstaged changes`	启动变基时工作树未干净	执行 `git stash` ，完成变基后执行 `git stash pop`
`fatal: refusing to merge unrelated histories`	合并两个无共同祖先的仓库	执行一次 `git merge --allow-unrelated-histories` ；调查历史分叉原因
变基后出现 `error: failed to push some refs`	远程分支已分叉（重写了共享历史）	如果分支仅你使用： `git push --force-with-lease` 。如果是共享分支：请勿强制推送，改用合并
bisect/checkout后出现 `detached HEAD state`	HEAD指向提交SHA而非分支	执行 `git checkout -b <new-branch>` 保存工作，或 `git checkout <branch-name>` 返回原分支
`Your local changes would be overwritten by checkout`	未提交的变更与目标分支冲突	先提交或暂存变更： `git stash push -m "wip: context"` ，然后切换分支

References

参考资料

For detailed content on specific topics, read the relevant file from

references/

```
references/rebase-strategies.md
```
- Rebase workflows, when to rebase vs merge, interactive rebase recipes for common scenarios

Only load a references file if the current task requires deep detail on that topic.

如需特定主题的详细内容，请阅读

references/

中的相关文件：

```
references/rebase-strategies.md
```
- 变基工作流、变基与合并的选择、常见场景的交互式变基方案

仅当当前任务需要该主题的深度细节时，才加载参考文件。