git-rebase-patterns

Git Rebase のパターン

線形な履歴の維持、積み重ねた PR の管理、コミット履歴の整理に役立つ高度なリベース手法です。

このスキルを使う場面

次のような場合にこのスキルを使用します	次のような場合は別のものを使用します
更新された 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

スカッシュマージ戦略

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 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

高度なリベースフラグ

Cherry-Pick の再適用（--reapply-cherry-picks）

問題： トランクをフィーチャーブランチに何度もマージした後（git merge main を使用）、最新のトランクにリベースしたい場合があります。デフォルトのリベース動作では、競合が発生したり、コミットが重複したりすることがあります。

解決策： --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 チェーン）では、あるブランチをリベースするたびに、依存するすべてのブランチを手動でリベースする必要があります。スタック内のブランチ間でコミットを移動するのは手間がかかります。

解決策： --update-refs は、リベース時にチェーン内のすべてのブランチを自動的に更新します。インタラクティブリベースと組み合わせると、1 回の操作で 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 チェーン）を管理する場合
• 複数のブランチにわたってコミットを再編成する場合
• リベース中にブランチ階層の同期を維持する場合

ベースの明示的な指定（--onto）

問題： Git による自動ベース検出が曖昧、または正しくない場合があります。コミットのリベース先を正確に指定したい場合があります。

解決策： --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	最近の作業を更新されたトランクにリベースする
ブランチのベースを変更する	git rebase --onto <new-base> <old-base>	誤ったベースから作成されたブランチを修正する
コミット範囲を切り出す	git rebase --onto <target> <start>^ <end>	特定のコミットを新しい場所に移動する
onto を指定したインタラクティブリベース	git rebase -i --onto <base> HEAD~N	直近 N 個のコミットを整理してリベースする

使用する場面：

• Git の自動ベース検出を信頼できない場合
• 最近の特定数のコミットをリベースする場合（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'

クイックリファレンス

操作	コマンド
main にリベースする	git rebase main
インタラクティブリベース	git rebase -i HEAD~N
Cherry-Pick を整理してリベースする	git rebase --reapply-cherry-picks origin/main
積み重ねた PR をリベースする	git rebase --update-refs main
直近 N 個のコミットをリベースする	git rebase --onto origin/main HEAD~N
ブランチのベースを変更する	git rebase --onto <new> <old>
失敗したリベースを中止する	git rebase --abort
競合の後に続行する	git rebase --continue
問題のあるコミットをスキップする	git rebase --skip

トラブルシューティング

リベースの競合が複雑すぎる場合

# 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}