Initial commit

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
+```

references/merge-options.md

@@ -0,0 +1,290 @@
+# Git Chain Merge Options
+
+Comprehensive reference for `git chain merge` command options, strategies, and reporting.
+
+## How Merge Works
+
+Git chain merge updates each branch by merging the parent branch into it:
+1. Checks out each branch in chain order
+2. Merges the parent branch into it
+3. Creates merge commits (unless fast-forward is possible)
+
+Unlike rebase, merge preserves the original commit history.
+
+## Basic Options
+
+### --verbose, -v
+
+Provides detailed output during the merging process.
+
+```bash
+git chain merge --verbose
+```
+
+Shows exactly what's happening with each branch, including Git's merge output.
+
+### --ignore-root, -i
+
+Skips merging the root branch into the first chain branch.
+
+```bash
+git chain merge --ignore-root
+```
+
+**Use when:**
+- Only want to propagate changes between chain branches
+- Root branch has changes you don't want incorporated yet
+
+### --stay
+
+Don't return to the original branch after merging.
+
+```bash
+git chain merge --stay
+```
+
+By default, git-chain returns you to your starting branch. Use this flag to remain on the last merged branch.
+
+### --chain=<name>
+
+Operate on a specific chain other than the current one.
+
+```bash
+git chain merge --chain=feature-x
+```
+
+Allows merging a chain even when not on a branch that belongs to it.
+
+## Merge Behavior Controls
+
+### --simple, -s
+
+Use simple merge mode without advanced detection.
+
+```bash
+git chain merge --simple
+```
+
+Disables fork-point detection and squashed merge handling for a faster, simpler merge process.
+
+### --fork-point, -f
+
+Use Git's fork-point detection (default behavior).
+
+```bash
+git chain merge --fork-point
+```
+
+Explicitly enables fork-point detection for finding better merge bases.
+
+### --no-fork-point
+
+Disable fork-point detection, use regular merge-base.
+
+```bash
+git chain merge --no-fork-point
+```
+
+Can be faster but potentially less accurate. Useful for repositories with limited reflog history.
+
+### --squashed-merge=<mode>
+
+How to handle branches that appear squash-merged.
+
+```bash
+# Reset branch to match parent (default)
+git chain merge --squashed-merge=reset
+
+# Skip branches that appear squashed
+git chain merge --squashed-merge=skip
+
+# Force merge despite detection
+git chain merge --squashed-merge=merge
+```
+
+## Git Merge Options
+
+### Fast-Forward Behavior
+
+```bash
+# Allow fast-forward if possible (default)
+git chain merge --ff
+
+# Always create a merge commit
+git chain merge --no-ff
+
+# Only allow fast-forward merges (fail if real merge needed)
+git chain merge --ff-only
+```
+
+### --squash
+
+Create a single commit instead of a merge commit.
+
+```bash
+git chain merge --squash
+```
+
+Combines all changes from the source branch into a single commit.
+
+### --strategy=<strategy>
+
+Use a specific Git merge strategy.
+
+```bash
+git chain merge --strategy=recursive
+git chain merge --strategy=ours
+git chain merge --strategy=resolve
+```
+
+Available strategies:
+- `recursive` (default) - 3-way merge
+- `resolve` - 3-way merge with fewer renames
+- `ours` - Keep our version for all conflicts
+- `octopus` - For merging more than two heads
+
+### --strategy-option=<option>
+
+Pass strategy-specific options.
+
+```bash
+# Ignore whitespace changes
+git chain merge --strategy=recursive --strategy-option=ignore-space-change
+
+# Use patience diff algorithm
+git chain merge --strategy=recursive --strategy-option=patience
+
+# Prefer ours in conflicts
+git chain merge --strategy=recursive --strategy-option=ours
+```
+
+## Reporting Options
+
+### --report-level=<level>
+
+Adjust the level of detail in the merge report.
+
+```bash
+# Basic success/failure messages
+git chain merge --report-level=minimal
+
+# Summary with counts (default)
+git chain merge --report-level=standard
+
+# Comprehensive per-branch details
+git chain merge --report-level=detailed
+```
+
+### --no-report
+
+Suppress the merge summary report entirely.
+
+```bash
+git chain merge --no-report
+```
+
+### --detailed-report
+
+Same as `--report-level=detailed`.
+
+```bash
+git chain merge --detailed-report
+```
+
+## Conflict Handling
+
+### When Conflicts Occur
+
+1. Git chain stops at the conflicted branch
+2. Repository is left in conflicted state
+3. Shows which branches conflicted and which files
+
+### Resolution Process
+
+```bash
+# 1. See conflicted files
+git status
+
+# 2. Resolve conflicts (edit files, remove markers)
+vim <conflicted-file>
+
+# 3. Stage resolved files
+git add <resolved-files>
+
+# 4. Complete the merge
+git commit
+
+# 5. Continue with remaining branches
+git chain merge
+```
+
+### Example Conflict Output
+
+```
+Processing branch: feature/auth
+Merge made by the 'recursive' strategy.
+ src/config.js | 10 ++++++++++
+ 1 file changed, 10 insertions(+)
+
+Processing branch: feature/profiles
+Merge conflict between feature/auth and feature/profiles:
+Auto-merging src/models/user.js
+CONFLICT (content): Merge conflict in src/models/user.js
+
+Merge Summary for Chain: feature
+  Successful merges: 1
+  Merge conflicts: 1
+     - feature/auth into feature/profiles
+```
+
+## Example Workflows
+
+### Update Open PRs Without Breaking Comments
+
+```bash
+# Merge preserves commits, keeping PR review comments
+git chain merge
+git chain push
+```
+
+### Update Specific Chain While on Unrelated Branch
+
+```bash
+git chain merge --chain=feature-login --verbose
+```
+
+### Clean History With No Extra Merge Commits
+
+```bash
+git chain merge --ff-only
+```
+
+Only updates branches that can be fast-forwarded.
+
+### Handle Squashed Branches
+
+```bash
+# Skip branches that appear squash-merged
+git chain merge --squashed-merge=skip
+```
+
+### Maximum Information for Complex Merges
+
+```bash
+git chain merge --verbose --detailed-report
+```
+
+## When to Use Merge vs Rebase
+
+### Use Merge When:
+- Branches have open pull requests with review comments
+- You want to preserve complete development history
+- Need to maintain context of commits for reviewers
+- Collaborating with others on the same branches
+- Branches have already been pushed/shared
+
+### Use Rebase When:
+- Working on private branches that haven't been shared
+- You prefer a linear, cleaner history
+- PRs haven't been reviewed yet
+- Want each branch's changes to appear fresh

references/rebase-options.md

@@ -0,0 +1,205 @@
+# Git Chain Rebase Options
+
+Comprehensive reference for `git chain rebase` command options and conflict handling.
+
+## How Rebase Works
+
+Git chain rebase updates each branch in sequence by:
+1. Finding the fork-point (where branch diverged from parent)
+2. Rebasing branch commits onto the updated parent
+3. Moving to the next branch in the chain
+
+The underlying command is:
+```bash
+git rebase --keep-empty --onto <parent_branch> <fork_point> <branch>
+```
+
+## Command Options
+
+### --step, -s
+
+Rebase one branch at a time, requiring manual confirmation between steps.
+
+```bash
+git chain rebase --step
+```
+
+**Use when:**
+- Anticipating conflicts and want to handle each branch separately
+- Need to review changes before proceeding to next branch
+- Debugging issues in the rebase process
+
+### --ignore-root, -i
+
+Skip rebasing the first branch onto the root branch.
+
+```bash
+git chain rebase --ignore-root
+```
+
+**Use when:**
+- Only want to update relationships between chain branches
+- Root branch has changes you don't want to incorporate yet
+- Testing chain structure without full update
+
+### Combined Options
+
+```bash
+# Step through without updating from root
+git chain rebase --step --ignore-root
+```
+
+## Fork-Point Detection
+
+Git chain uses sophisticated fork-point detection:
+
+1. **First**: Checks if branch can be fast-forwarded
+2. **Then**: Uses Git's reflog to find original branching point
+3. **Fallback**: Uses regular merge-base if fork-point fails
+
+### When Fork-Point Detection Fails
+
+Fork-point may fail when:
+- Reflog entries have been cleaned by `git gc`
+- Branch was created from an older commit (not tip) of parent
+- Repository history was affected by certain operations
+
+In these cases, git-chain falls back to `git merge-base` which finds the most recent common ancestor.
+
+## Squash Merge Detection
+
+Git chain detects when a branch has been squash-merged into its parent:
+- Compares the diff between branch and parent
+- If empty diff, assumes branch was squash-merged
+- Prevents duplicate changes from being rebased
+
+## Conflict Handling
+
+### When Conflicts Occur
+
+1. **Detection**: Git chain stops at the conflicted commit
+2. **State**: Repository is left in conflicted state for resolution
+3. **Information**: Shows which branch is being rebased and conflict location
+4. **Backups**: May create automatic backup branches
+
+### Resolution Steps
+
+```bash
+# 1. See which files are conflicted
+git status
+
+# 2. Edit conflicted files (look for markers)
+# <<<<<<<, =======, >>>>>>>
+
+# 3. Mark as resolved
+git add <resolved-files>
+
+# 4. Continue the rebase
+git rebase --continue
+
+# 5. Continue with remaining chain branches
+git chain rebase
+```
+
+### Aborting a Rebase
+
+If conflicts are too complex or you need to reconsider:
+
+```bash
+# Abort current rebase
+git rebase --abort
+
+# If backup branches exist, restore
+git checkout branch-name
+git reset --hard branch-name-backup
+```
+
+## Example Workflows
+
+### Standard Chain Update
+
+```bash
+# Update all branches from root through chain
+git chain rebase
+```
+
+### Careful Rebase with Review
+
+```bash
+# Process one branch at a time
+git chain rebase --step
+
+# After each branch:
+# - Review the rebased commits
+# - Run tests
+# - Press Enter to continue or Ctrl+C to stop
+```
+
+### Internal Chain Update Only
+
+```bash
+# Update branch relationships without incorporating root changes
+git chain rebase --ignore-root
+```
+
+### Conflict Workflow Example
+
+```bash
+$ git chain rebase
+Rebasing branch feature/auth onto master...
+Auto-merging src/auth.js
+CONFLICT (content): Merge conflict in src/auth.js
+error: could not apply 1a2b3c4... Add authentication feature
+
+# Resolve the conflict
+$ vim src/auth.js
+$ git add src/auth.js
+$ git rebase --continue
+Successfully rebased branch feature/auth
+
+# Git chain continues automatically
+Rebasing branch feature/profiles onto feature/auth...
+Successfully rebased branch feature/profiles
+```
+
+## Recovery Options
+
+### From Backup Branches
+
+If you used `git chain backup` before rebasing:
+
+```bash
+git checkout branch-name
+git reset --hard branch-name-backup
+
+# Clean up backup after restoring
+git branch -D branch-name-backup
+```
+
+### From Reflog
+
+Even without backups, Git's reflog tracks all branch movements:
+
+```bash
+# See branch history
+git reflog show branch-name
+
+# Reset to previous state
+git checkout branch-name
+git reset --hard branch-name@{1}  # Previous state
+git reset --hard branch-name@{2}  # Two states ago
+```
+
+### Abort In-Progress Rebase
+
+```bash
+git rebase --abort
+```
+
+## Best Practices
+
+1. **Create backups first**: `git chain backup` before complex rebases
+2. **Use --step for complex chains**: Easier to handle conflicts one branch at a time
+3. **Run tests after rebase**: Ensure nothing broke during the update
+4. **Don't rebase shared branches**: Only rebase private/local branches
+5. **Pull before rebase**: Ensure root branch is up to date