git-rebase-patterns

Git Rebase 模式

用于维护线性历史记录、管理堆叠 PR，以及清理提交历史的高级 rebase 技术。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他工具……
将功能分支 rebase 到更新后的 main	创建分支 → git-branch-naming
在 PR 前清理提交历史	创建 PR → git-branch-pr-workflow
管理堆叠 PR（PR 链）	简单提交 → git-commit-workflow
将包含大量合并的分支转换为线性历史	基本 Git 操作 → git-cli-agentic

线性历史基础

主干开发

# Feature branch lifecycle (keep short - max 2 days)
git switch main
git pull origin main
git switch -c feat/user-auth

# Daily rebase to stay current
git switch main && git pull
git switch feat/user-auth
git rebase main

# Interactive cleanup before PR
git rebase -i main
# Squash, fixup, reword commits for clean history

# Push and create PR
git push -u origin feat/user-auth

Squash 合并策略

维护线性的 main 分支历史：

# Manual squash merge
git switch main
git merge --squash feat/user-auth
git commit -m "feat: add user authentication system

- Implement JWT token validation
- Add login/logout endpoints
- Create user session management

Closes #123"

交互式 Rebase 工作流

在分享前清理提交：

# Rebase last 3 commits
git rebase -i HEAD~3

# Common rebase commands:
# pick   = use commit as-is
# squash = combine with previous commit
# fixup  = squash without editing message
# reword = change commit message
# drop   = remove commit entirely

# Example rebase todo list:
pick a1b2c3d feat: add login form
fixup d4e5f6g fix typo in login form
squash g7h8i9j add form validation
reword j1k2l3m implement JWT tokens

高级 Rebase 标志

重新应用 Cherry-Pick（--reapply-cherry-picks）

问题： 多次将主干合并到功能分支（通过 git merge main）后，你想将分支 rebase 到最新主干上。默认的 rebase 行为可能会产生冲突或重复提交。

解决方案： --reapply-cherry-picks 会检测已通过合并应用过的提交，并丢弃合并提交，只保留原始更改。

# Scenario: You merged main into your branch a few times
git log --oneline
# abc123 Merge branch 'main' into feat/auth
# def456 feat: add login endpoint
# ghi789 Merge branch 'main' into feat/auth
# jkl012 feat: add user validation

# Rebase onto fresh main, dropping merge commits
git fetch origin
git rebase --reapply-cherry-picks origin/main

# Result: Clean linear history with just your feature commits
# jkl012 feat: add user validation
# def456 feat: add login endpoint

适用场景：

• 为解决冲突而将主干合并到分支后
• 将包含大量合并的分支转换为线性历史
• 创建 PR 前清理集成合并

更新引用（--update-refs）

问题： 使用堆叠 PR（PR 链）时，rebase 一个分支需要手动 rebase 所有依赖分支。在堆叠中不同分支间移动提交也很麻烦。

解决方案： --update-refs 会在 rebase 时自动更新链中的所有分支。结合交互式 rebase，你可以通过一次操作重新组织整个 PR 堆叠中的提交。

# Scenario: Stacked PRs
# main <- feat/auth-base <- feat/auth-oauth <- feat/auth-refresh

# Rebase the entire stack onto updated main
git switch feat/auth-refresh
git rebase --update-refs main

# All three branches (auth-base, auth-oauth, auth-refresh) are updated
# No manual rebasing of each branch needed

# Interactive rebase to move commits between branches
git rebase -i --update-refs main

# In the editor, move commit lines around to reorganize the stack:
# pick abc123 feat: add auth base      # Will update feat/auth-base
# pick def456 feat: add OAuth support  # Will update feat/auth-oauth
# pick ghi789 feat: add token refresh  # Will update feat/auth-refresh

使用 update-refs 的堆叠 PR 工作流：

# Create PR stack
git switch main
git pull origin main

# First PR: Base authentication
git switch -c feat/auth-base
# ... make commits ...
git push -u origin feat/auth-base

# Second PR: OAuth (depends on first)
git switch -c feat/auth-oauth
# ... make commits ...
git push -u origin feat/auth-oauth

# Third PR: Token refresh (depends on second)
git switch -c feat/auth-refresh
# ... make commits ...
git push -u origin feat/auth-refresh

# Main updated - rebase entire stack
git fetch origin
git switch feat/auth-refresh
git rebase --update-refs origin/main

# All branches rebased in one command
git push --force-with-lease origin feat/auth-base
git push --force-with-lease origin feat/auth-oauth
git push --force-with-lease origin feat/auth-refresh

适用场景：

• 管理堆叠 PR（带依赖关系的 PR 链）
• 跨多个分支重新组织提交
• 在 rebase 期间保持分支层级同步

显式控制基点（--onto）

问题： Git 自动检测基点时可能会有歧义或出错。你希望精确控制提交 rebase 到的位置。

解决方案： --onto 可显式指定新的基点，绕过 Git 的基点检测启发式规则。

# Syntax: git rebase --onto <newbase> <upstream> <branch>
# Translates to: Take commits from <upstream>..<branch> and put them onto <newbase>

# Common pattern: Rebase last N commits onto a specific branch
git rebase --onto origin/develop HEAD~5
# Takes your last 5 commits and puts them on top of origin/develop
# Equivalent to: git rebase --onto origin/develop HEAD~5 HEAD

# Example: Move feature commits from old base to new base
# Scenario: You branched from develop, but should have branched from main
git switch feat/payment
git rebase --onto main develop feat/payment
# Takes commits from develop..feat/payment and moves them onto main

# Example: Rebase specific commit range
# Move commits from abc123 to def456 onto main
git rebase --onto main abc123^ def456
# The ^ includes abc123 in the range

# Example: Extract commits to new branch
# You have commits on feat/auth that should be on separate branch
git switch -c feat/auth-ui feat/auth  # Create new branch
git rebase --onto main feat/auth~3 feat/auth-ui
# Takes last 3 commits from feat/auth and puts them on main

常见的 --onto 模式：

模式	命令	使用场景
主干上的最近 N 个提交	git rebase --onto origin/main HEAD~N	将最近的工作 rebase 到更新后的主干上
更改分支基点	git rebase --onto <new-base> <old-base>	修正从错误基点创建的分支
提取提交范围	git rebase --onto <target> <start>^ <end>	将指定提交移动到新位置
使用 onto 进行交互式 rebase	git rebase -i --onto <base> HEAD~N	清理并 rebase 最近 N 个提交

适用场景：

• 不信任 Git 的自动基点检测时
• Rebase 指定数量的最近提交（HEAD~N 模式）
• 分支创建后更改其基点
• 将部分提交提取到新位置

组合使用高级标志

这些标志可以组合使用，构建强大的工作流：

# Rebase stacked PRs with cherry-pick detection
git rebase --reapply-cherry-picks --update-refs origin/main

# Interactive rebase with explicit base and branch updates
git rebase -i --onto origin/main HEAD~10 --update-refs

# Clean up merged history and update dependent branches
git rebase --reapply-cherry-picks --update-refs --onto origin/develop origin/main

冲突解决

# When rebase conflicts occur
git rebase main
# Fix conflicts in editor
git add resolved-file.txt
git rebase --continue

# If rebase gets messy, abort and merge instead
git rebase --abort
git merge main

安全强制推送

# Always use --force-with-lease to prevent overwriting others' work
git push --force-with-lease origin feat/branch-name

# Never force push to main/shared branches
# Use this alias for safety:
git config alias.pushf 'push --force-with-lease'

快速参考

操作	命令
Rebase 到 main 上	git rebase main
交互式 rebase	git rebase -i HEAD~N
Rebase 并清理 cherry-pick	git rebase --reapply-cherry-picks origin/main
Rebase 堆叠 PR	git rebase --update-refs main
Rebase 最近 N 个提交	git rebase --onto origin/main HEAD~N
更改分支基点	git rebase --onto <new> <old>
中止失败的 rebase	git rebase --abort
冲突后继续	git rebase --continue
跳过有问题的提交	git rebase --skip

故障排除

Rebase 冲突过于复杂

# Abort rebase and use merge instead
git rebase --abort
git merge main

分支与远程分支发生分叉

# Pull with rebase to maintain linear history
git pull --rebase origin feat/branch-name

# Or reset if local changes can be discarded
git fetch origin
git reset --hard origin/feat/branch-name

变基后提交丢失

# Find lost commits in reflog
git reflog

# Restore to previous state
git reset --hard HEAD@{N}