Git Chain

Git Chain

Overview

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.

When to Use This Skill

Use git-chain when:

• Stacked PRs: Working with multiple dependent pull requests that build on each other
• Feature chains: Developing a large feature split into incremental branches
• Review feedback: Updating base branches requires propagating changes to dependent branches
• Clean history: Maintaining linear commit history across dependent branches
• Avoiding tedious rebasing: Don't want to manually rebase 3+ branches in sequence

Prerequisites

CRITICAL: Before proceeding, verify that git-chain is installed:

git chain --version

If git-chain is not installed:

• DO NOT attempt to install it automatically
• STOP and inform the user that git-chain is required
• RECOMMEND manual installation:

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

Key Concepts

• Chain: A named sequence of branches with dependency order
• Root Branch: Foundation branch (typically main or master) - NOT part of the chain
• Branch Order: The sequence in which branches depend on each other

Important: A branch can belong to at most one chain.

Basic Workflow

Step 1: Set Up a 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.

Step 2: View the Chain

git chain          # Show current chain (if on a chain branch)
git chain list     # List all chains in the repository

Step 3: Update the Chain

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

Common Patterns

Pattern 1: Stacked PR Workflow

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

Pattern 2: Review Feedback on Base Branch

Scenario: Reviewer requested changes on auth branch (first PR)

git checkout auth
# ... make changes, commit ...

# Update dependent branches automatically
git chain rebase

Pattern 3: Adding a New Branch to Existing Chain

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

Core Commands Reference

Rebase vs Merge

Use Rebase When:

• Branches are private/not shared
• You prefer clean, linear history
• PRs haven't been reviewed yet

Use Merge When:

• Branches have open PRs with review comments
• You need to preserve commit history
• Collaborating with others on the same branches

Advanced Usage

For comprehensive coverage of all flags and advanced patterns, see:

• references/rebase-options.md - All rebase flags and conflict handling
• references/merge-options.md - All merge flags and strategies
• references/chain-management.md - Moving, reorganizing, and removing chains

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)

Recovery

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}

Handling Conflicts

When conflicts occur during git chain rebase:

1. Git-chain pauses at the conflicted commit
2. Resolve conflicts manually in the marked files
3. git add <resolved-files>
4. git rebase --continue
5. git chain rebase (continues with remaining branches)

Troubleshooting

"Branch not part of any chain"

• Run git chain list to see available chains
• Use git chain init to add the current branch to a chain

"Cannot find fork-point"

• Reflog may have been cleaned up
• Use --no-fork-point flag to fall back to merge-base

Rebase conflicts on every update

• Consider using git chain merge instead to preserve history
• Or use --step flag to handle each branch individually

Squash-merged branch causing issues

• git-chain detects squash merges; use --squashed-merge=skip to skip them
• Or use --squashed-merge=reset (default) to reset branch to parent