437 lines
8.6 KiB
Markdown
437 lines
8.6 KiB
Markdown
# 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
|
|
```
|