Manage and rebase chains of dependent Git branches (stacked branches). Use when working with multiple dependent PRs, feature branches that build on each other, or maintaining clean branch hierarchies.
git chain manages chains of dependent Git branches where each branch builds upon the previous one (stacked branches). Instead of manually rebasing each branch in sequence, git-chain tracks relationships and updates all branches with a single command.
I---J---K feature-2
/
E---F---G feature-1
/
A---B---C---D master
When master is updated, git-chain rebases feature-1 onto master, then feature-2 onto feature-1 automatically.
Use git-chain when:
CRITICAL: Before proceeding, verify that git-chain is installed:
git chain --version
If git-chain is not installed:
# From source (requires Rust)
git clone git@github.com:dashed/git-chain.git
cd git-chain
make install
# Or with Cargo
cargo install --path .
If git-chain is not available, exit gracefully and do not proceed with the workflow below.
main or master) - NOT part of the chainImportant: A branch can belong to at most one chain.
Create a chain with your stacked branches:
git chain setup my-feature master feature-1 feature-2 feature-3
This creates chain "my-feature" with master as root and branches in order: feature-1 -> feature-2 -> feature-3.
git chain # Show current chain (if on a chain branch)
git chain list # List all chains in the repository
When the root branch or any branch in the chain has new commits:
Option A: Rebase (rewrites history, clean linear commits)
git chain rebase
Option B: Merge (preserves history, creates merge commits)
git chain merge
Scenario: Working on a feature split into 3 PRs: auth, profiles, settings
# Create branches
git checkout -b auth main
# ... make auth changes, commit ...
git checkout -b profiles auth
# ... make profile changes, commit ...
git checkout -b settings profiles
# ... make settings changes, commit ...
# Set up the chain
git chain setup user-feature main auth profiles settings
# After main receives new commits, update all branches
git chain rebase
git chain push --force # Update all PRs
Scenario: Reviewer requested changes on auth branch (first PR)
git checkout auth
# ... make changes, commit ...
# Update dependent branches automatically
git chain rebase
Scenario: Need to add notifications branch between profiles and settings
git checkout -b notifications profiles
# ... make changes, commit ...
# Add to chain with specific position
git chain init user-feature main --after=profiles
| Command | Description |
|---|---|
git chain setup <name> <root> <b1> <b2>... |
Create chain with branches |
git chain init <name> <root> |
Add current branch to chain |
git chain |
Display current chain |
git chain list |
List all chains |
git chain rebase |
Rebase all branches (rewrites history) |
git chain merge |
Merge all branches (preserves history) |
git chain push |
Push all branches to remotes |
git chain push --force |
Force push all branches |
git chain first/last/next/prev |
Navigate between chain branches |
git chain backup |
Create backup branches |
git chain prune |
Remove branches merged to root |
git chain remove |
Remove current branch from chain |
git chain remove --chain |
Delete entire chain |
Use Rebase When:
Use Merge When:
For comprehensive coverage of all flags and advanced patterns, see:
Key flags:
--step, -s: Process one branch at a time (rebase)--ignore-root, -i: Skip updating first branch from root--verbose, -v: Detailed output (merge)--chain=<name>: Operate on specific chain--no-ff: Force merge commits even for fast-forwards--squashed-merge=<mode>: Handle squash-merged branches (reset/skip/merge)If something goes wrong during rebase:
# Abort in-progress rebase
git rebase --abort
# Restore from backup (if created with git chain backup)
git checkout branch-name
git reset --hard branch-name-backup
# Or use reflog
git reflog
git reset --hard branch-name@{1}
When conflicts occur during git chain rebase:
git add <resolved-files>git rebase --continuegit chain rebase (continues with remaining branches)"Branch not part of any chain"
git chain list to see available chainsgit chain init to add the current branch to a chain"Cannot find fork-point"
--no-fork-point flag to fall back to merge-baseRebase conflicts on every update
git chain merge instead to preserve history--step flag to handle each branch individuallySquash-merged branch causing issues
--squashed-merge=skip to skip them--squashed-merge=reset (default) to reset branch to parent