Git Chain

Overview

git chain

                        I---J---K  feature-2
                       /
              E---F---G  feature-1
             /
A---B---C---D  master

When

master

feature-1

master

feature-2

feature-1

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

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

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

profiles

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

git chain setup <name> <root> <b1> <b2>...

git chain init <name> <root>

git chain

git chain list

git chain rebase

git chain merge

git chain push

git chain push --force

git chain first/last/next/prev

git chain backup

git chain prune

git chain remove

git chain remove --chain

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