5.7 KiB
Git Chain Management
Comprehensive reference for creating, modifying, and navigating branch chains.
Creating Chains
git chain setup
Create a new chain with multiple branches at once.
git chain setup <chain_name> <root_branch> <branch_1> <branch_2> ... <branch_N>
Example:
git chain setup user-feature main auth profiles settings
Creates chain "user-feature" with:
- Root:
main(not part of the chain) - Order:
auth->profiles->settings
git chain init
Add the current branch to a chain.
# Add to end of chain (default)
git chain init <chain_name> <root_branch>
# Add at specific position
git chain init <chain_name> <root_branch> --before=<other_branch>
git chain init <chain_name> <root_branch> --after=<other_branch>
git chain init <chain_name> <root_branch> --first
Examples:
# Add current branch at end
git checkout notifications
git chain init user-feature main
# Add before settings
git chain init user-feature main --before=settings
# Add after profiles
git chain init user-feature main --after=profiles
# Add as first branch in chain
git chain init user-feature main --first
Viewing Chains
git chain
Display the current chain (if current branch is part of one).
git chain
Shows:
- Chain name
- Root branch
- All branches in order
- Current branch indicator
git chain list
List all chains in the repository.
git chain list
Modifying Chains
git chain move
Move a branch within its chain or to a different chain.
# Move to different position in same chain
git chain move --before=<other_branch>
git chain move --after=<other_branch>
# Move to different chain
git chain move --chain=<other_chain_name>
Examples:
# Move current branch before settings
git chain move --before=settings
# Move current branch after auth
git chain move --after=auth
# Move to a different chain
git chain move --chain=api-feature
git chain rename
Rename the current chain.
git chain rename <new_chain_name>
Example:
git chain rename user-management
Removing from Chains
git chain remove
Remove the current branch from its chain.
git chain remove
Note: This only removes the branch from the chain metadata. The branch itself still exists.
git chain remove --chain
Remove the entire chain.
# Remove the current chain
git chain remove --chain
# Remove a specific chain
git chain remove --chain=<chain_name>
Note: This removes the chain metadata only. All branches continue to exist.
Chain Navigation
Navigate between branches in a chain without remembering branch names.
git chain first
Switch to the first branch in the chain.
git chain first
git chain last
Switch to the last branch in the chain.
git chain last
git chain next
Switch to the next branch in the chain.
git chain next
git chain prev
Switch to the previous branch in the chain.
git chain prev
Navigation Example:
# Chain: auth -> profiles -> settings
# Currently on: profiles
git chain next # Switches to settings
git chain prev # Switches back to profiles
git chain first # Switches to auth
git chain last # Switches to settings
Utility Commands
git chain backup
Create backup branches for all branches in the chain.
git chain backup
Creates branches named <branch-name>-backup for each branch.
Use before:
- Complex rebases
- Experimental changes
- When you want a safety net
git chain push
Push all branches in the chain to their remotes.
# Normal push
git chain push
# Force push (uses --force-with-lease for safety)
git chain push --force
Useful for:
- Updating all PRs at once
- After rebasing the chain
git chain prune
Remove branches that have been merged to the root branch.
git chain prune
Detects and removes branches whose changes are already in the root branch.
Chain Storage
Git chain stores relationships in your repository's Git config:
- Which chain a branch belongs to
- The order of branches within a chain
- Each branch's root branch
You can view this with:
git config --get-regexp chain
Example Workflows
Creating a Feature Chain from Scratch
# Create base branch
git checkout -b auth main
# ... develop auth feature ...
git commit -m "Add authentication"
# Create dependent branch
git checkout -b profiles auth
# ... develop profiles feature ...
git commit -m "Add user profiles"
# Create another dependent branch
git checkout -b settings profiles
# ... develop settings feature ...
git commit -m "Add settings page"
# Set up the chain
git chain setup user-features main auth profiles settings
Inserting a Branch Mid-Chain
# Need to add notifications between profiles and settings
git checkout -b notifications profiles
# ... develop notifications ...
git commit -m "Add notifications"
# Add to chain in correct position
git chain init user-features main --after=profiles
Reorganizing a Chain
# Move notifications to be first
git checkout notifications
git chain move --before=auth
# Or move to after settings
git chain move --after=settings
Cleaning Up After Merges
# After auth PR is merged to main
git chain prune # Removes auth from chain
# Chain is now: profiles -> settings (with main as root)
Splitting a Chain
# Remove middle branch to create two chains
git checkout profiles
git chain remove
# Now auth is alone in user-features chain
# Create new chain for profiles and settings
git checkout profiles
git chain init profile-features main
git checkout settings
git chain init profile-features main --after=profiles