Initial commit

references/configuration.md

@@ -0,0 +1,436 @@
+# Configuration Reference
+
+Complete guide to configuring git-absorb behavior via `.gitconfig`.
+
+## Quick Reference
+
+```toml
+[absorb]
+    maxStack = 50
+    oneFixupPerCommit = true
+    autoStageIfNothingStaged = true
+    fixupTargetAlwaysSHA = false
+    forceAuthor = false
+    forceDetach = false
+    createSquashCommits = false
+```
+
+## Configuration Options
+
+### `maxStack`
+
+**Default:** `10`
+
+**Purpose:** Maximum number of commits to search when run without `--base`.
+
+**When to configure:**
+- Working on feature branches with >10 commits
+- Seeing "WARN stack limit reached" messages
+- Want to absorb into older commits
+
+**Recommended values:**
+- Small projects: `20-30`
+- Medium projects: `50`
+- Large feature branches: `100+`
+
+**Configuration:**
+```bash
+# Local (current repository only)
+git config absorb.maxStack 50
+
+# Global (all repositories)
+git config --global absorb.maxStack 50
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    maxStack = 50
+```
+
+**Warning message when limit reached:**
+```
+WARN stack limit reached, limit: 10
+```
+
+**Alternative:** Use `--base <branch>` flag to specify range without changing config:
+```bash
+git absorb --base main  # searches all commits since main
+```
+
+---
+
+### `oneFixupPerCommit`
+
+**Default:** `false`
+
+**Purpose:** Generate only one fixup commit per target commit instead of per hunk.
+
+**Effect:**
+- `false`: Multiple fixup commits if multiple hunks absorb into same commit
+- `true`: Single consolidated fixup commit per target
+
+**When to enable:**
+- Prefer cleaner rebase history
+- Don't need per-hunk granularity
+- Many small changes to same commits
+
+**Configuration:**
+```bash
+git config absorb.oneFixupPerCommit true
+git config --global absorb.oneFixupPerCommit true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    oneFixupPerCommit = true
+```
+
+**Example difference:**
+
+Without `oneFixupPerCommit`:
+```
+fixup! Add feature X  (for hunk 1)
+fixup! Add feature X  (for hunk 2)
+fixup! Add feature X  (for hunk 3)
+```
+
+With `oneFixupPerCommit`:
+```
+fixup! Add feature X  (all hunks consolidated)
+```
+
+**Command-line alternative:**
+```bash
+git absorb --one-fixup-per-commit
+```
+
+---
+
+### `autoStageIfNothingStaged`
+
+**Default:** `false`
+
+**Purpose:** Automatically stage all changes when nothing is staged.
+
+**Effect:**
+- `false`: Only consider explicitly staged files (requires `git add`)
+- `true`: Auto-stage all changes if index is empty, unstage remainder after absorb
+
+**When to enable:**
+- Frequently run `git add .` before absorbing
+- Want streamlined workflow
+- Trust git-absorb with all working directory changes
+
+**Configuration:**
+```bash
+git config absorb.autoStageIfNothingStaged true
+git config --global absorb.autoStageIfNothingStaged true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    autoStageIfNothingStaged = true
+```
+
+**Workflow with this enabled:**
+```bash
+# Make changes (don't stage)
+vim file1.py file2.py
+
+# Run absorb directly (no git add needed)
+git absorb --and-rebase
+# -> auto-stages all changes
+# -> absorbs what it can
+# -> unstages remainder
+```
+
+**Warning:** Be careful with this if you have unrelated changes in working directory.
+
+---
+
+### `fixupTargetAlwaysSHA`
+
+**Default:** `false`
+
+**Purpose:** Always use commit SHA in fixup messages instead of commit summary.
+
+**Effect:**
+- `false`: Use commit summary if unique, fall back to SHA for duplicates
+- `true`: Always use SHA
+
+**When to enable:**
+- Commit messages have many duplicates
+- Prefer consistency in fixup references
+- Working with auto-generated commit messages
+
+**Configuration:**
+```bash
+git config absorb.fixupTargetAlwaysSHA true
+git config --global absorb.fixupTargetAlwaysSHA true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    fixupTargetAlwaysSHA = true
+```
+
+**Example difference:**
+
+Default (`false`):
+```
+fixup! Add user authentication
+fixup! abc123  (if "Add user authentication" appears multiple times)
+```
+
+With `fixupTargetAlwaysSHA = true`:
+```
+fixup! abc123
+fixup! def456
+```
+
+---
+
+### `forceAuthor`
+
+**Default:** `false`
+
+**Purpose:** Generate fixups for commits authored by anyone, not just you.
+
+**Effect:**
+- `false`: Only modify your own commits (filtered by git author)
+- `true`: Can modify any author's commits
+
+**When to enable:**
+- Pair programming environments
+- Shared feature branches with multiple authors
+- Taking over someone else's work
+
+**Configuration:**
+```bash
+git config absorb.forceAuthor true
+git config --global absorb.forceAuthor true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    forceAuthor = true
+```
+
+**Security consideration:** Only enable if you have permission to modify others' commits.
+
+**Command-line alternative:**
+```bash
+git absorb --force-author
+```
+
+---
+
+### `forceDetach`
+
+**Default:** `false`
+
+**Purpose:** Allow generating fixups when HEAD is detached (not on a branch).
+
+**Effect:**
+- `false`: Refuse to run when HEAD is detached
+- `true`: Run even in detached HEAD state
+
+**When to enable:**
+- Frequently work in detached HEAD state
+- Using git-absorb during cherry-pick/bisect workflows
+- Advanced git workflows
+
+**Configuration:**
+```bash
+git config absorb.forceDetach true
+git config --global absorb.forceDetach true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    forceDetach = true
+```
+
+**Warning:** Detached HEAD state can be confusing. Only enable if you understand the implications.
+
+**Command-line alternative:**
+```bash
+git absorb --force-detach
+```
+
+---
+
+### `createSquashCommits`
+
+**Default:** `false`
+
+**Purpose:** Generate squash commits instead of fixup commits.
+
+**Effect:**
+- `false`: Create `fixup!` commits (message discarded during autosquash)
+- `true`: Create `squash!` commits (message kept and editable during autosquash)
+
+**When to enable:**
+- Need to document why changes were added
+- Want to edit commit messages during rebase
+- Organizational requirements for commit message detail
+
+**Configuration:**
+```bash
+git config absorb.createSquashCommits true
+git config --global absorb.createSquashCommits true
+```
+
+**In .gitconfig:**
+```toml
+[absorb]
+    createSquashCommits = true
+```
+
+**Example difference:**
+
+With `fixup!` (default):
+```
+fixup! Add feature X
+# During rebase: message discarded, change absorbed silently
+```
+
+With `squash!` (createSquashCommits = true):
+```
+squash! Add feature X
+# During rebase: editor opens, can edit combined message
+```
+
+**Command-line alternative:**
+```bash
+git absorb --squash
+```
+
+---
+
+## Configuration Scope
+
+### Local vs Global
+
+**Local** (repository-specific):
+```bash
+git config absorb.maxStack 50
+```
+- Stored in `.git/config`
+- Only affects current repository
+- Use for project-specific settings
+
+**Global** (all repositories):
+```bash
+git config --global absorb.maxStack 50
+```
+- Stored in `~/.gitconfig`
+- Affects all repositories
+- Use for personal preferences
+
+### Checking Current Configuration
+
+**View all absorb settings:**
+```bash
+git config --get-regexp absorb
+```
+
+**View specific setting:**
+```bash
+git config absorb.maxStack
+```
+
+**View with source:**
+```bash
+git config --list --show-origin | grep absorb
+```
+
+### Removing Configuration
+
+**Remove local setting:**
+```bash
+git config --unset absorb.maxStack
+```
+
+**Remove global setting:**
+```bash
+git config --global --unset absorb.maxStack
+```
+
+---
+
+## Recommended Configurations
+
+### Conservative (default behavior)
+```toml
+[absorb]
+    maxStack = 10
+    oneFixupPerCommit = false
+    autoStageIfNothingStaged = false
+    fixupTargetAlwaysSHA = false
+    forceAuthor = false
+    forceDetach = false
+    createSquashCommits = false
+```
+
+### Balanced (recommended for most users)
+```toml
+[absorb]
+    maxStack = 50
+    oneFixupPerCommit = true
+    autoStageIfNothingStaged = false
+    fixupTargetAlwaysSHA = false
+    forceAuthor = false
+    forceDetach = false
+    createSquashCommits = false
+```
+
+### Aggressive (streamlined workflow)
+```toml
+[absorb]
+    maxStack = 100
+    oneFixupPerCommit = true
+    autoStageIfNothingStaged = true
+    fixupTargetAlwaysSHA = false
+    forceAuthor = true
+    forceDetach = false
+    createSquashCommits = false
+```
+
+### Team collaboration
+```toml
+[absorb]
+    maxStack = 50
+    oneFixupPerCommit = true
+    autoStageIfNothingStaged = false
+    fixupTargetAlwaysSHA = true
+    forceAuthor = true  # Allow fixing teammates' commits
+    forceDetach = false
+    createSquashCommits = false
+```
+
+---
+
+## Command-Line Flags Override Configuration
+
+All configuration options can be overridden with command-line flags:
+
+| Configuration | Command-Line Flag |
+|--------------|-------------------|
+| `oneFixupPerCommit` | `--one-fixup-per-commit` / `-F` |
+| `forceAuthor` | `--force-author` |
+| `forceDetach` | `--force-detach` |
+| `createSquashCommits` | `--squash` / `-s` |
+| `maxStack` | `--base <commit>` |
+
+**Example:**
+```bash
+# Even with forceAuthor = false in config
+git absorb --force-author  # Will absorb into any author's commits
+```