Initial commit

2025-11-29 18:17:49 +08:00
commit 75d4bfb435
7 changed files with 1113 additions and 0 deletions
--- a/references/chain-management.md
+++ b/references/chain-management.md
@@ -0,0 +1,315 @@
+# 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.
+
+```bash
+git chain setup <chain_name> <root_branch> <branch_1> <branch_2> ... <branch_N>
+```
+
+**Example:**
+```bash
+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.
+
+```bash
+# 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:**
+```bash
+# 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).
+
+```bash
+git chain
+```
+
+Shows:
+- Chain name
+- Root branch
+- All branches in order
+- Current branch indicator
+
+### git chain list
+
+List all chains in the repository.
+
+```bash
+git chain list
+```
+
+## Modifying Chains
+
+### git chain move
+
+Move a branch within its chain or to a different chain.
+
+```bash
+# 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:**
+```bash
+# 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.
+
+```bash
+git chain rename <new_chain_name>
+```
+
+**Example:**
+```bash
+git chain rename user-management
+```
+
+## Removing from Chains
+
+### git chain remove
+
+Remove the current branch from its chain.
+
+```bash
+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.
+
+```bash
+# 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.
+
+```bash
+git chain first
+```
+
+### git chain last
+
+Switch to the last branch in the chain.
+
+```bash
+git chain last
+```
+
+### git chain next
+
+Switch to the next branch in the chain.
+
+```bash
+git chain next
+```
+
+### git chain prev
+
+Switch to the previous branch in the chain.
+
+```bash
+git chain prev
+```
+
+**Navigation Example:**
+```bash
+# 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.
+
+```bash
+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.
+
+```bash
+# 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.
+
+```bash
+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:
+```bash
+git config --get-regexp chain
+```
+
+## Example Workflows
+
+### Creating a Feature Chain from Scratch
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+```