7.4 KiB
Advanced Usage
This document covers all command-line flags and advanced usage patterns for git-absorb.
Complete Flag Reference
Core Flags
--and-rebase / -r
Run rebase automatically after creating fixup commits.
When to use:
- You trust git-absorb's output
- You want a streamlined workflow
- Changes are straightforward
Example:
git absorb --and-rebase
--dry-run / -n
Preview what would happen without making any changes.
When to use:
- First time using git-absorb on a branch
- Testing if changes will absorb correctly
- Understanding which commits would be affected
Example:
git absorb --dry-run
--base <commit> / -b <commit>
Specify the base commit for the absorb stack.
When to use:
- Feature branch has more than 10 commits (default limit)
- Want to absorb into commits since a specific branch point
- Getting "stack limit reached" warnings
Examples:
# Absorb into all commits since main
git absorb --base main
# Absorb into all commits since specific SHA
git absorb --base abc123
Safety and Control Flags
--force
Skip all safety checks (equivalent to all --force-* flags).
When to use:
- Need to bypass author filtering AND detached HEAD restrictions
- Understand the risks and have reviewed changes
Warning: Use with caution. This disables protective checks.
Example:
git absorb --force --and-rebase
--force-author
Generate fixups for commits not authored by you.
When to use:
- Pair programming with teammate's commits
- Maintaining a branch with multiple authors
- Cleaning up inherited code
Example:
git absorb --force-author --and-rebase
--force-detach
Generate fixups even when HEAD is detached (not on a branch).
When to use:
- Working in detached HEAD state intentionally
- Cherry-picking workflow
- Advanced git operations
Example:
git absorb --force-detach
Output Format Flags
--one-fixup-per-commit / -F
Generate only one fixup commit per target commit (instead of per hunk).
When to use:
- Want cleaner commit history during rebase
- Multiple hunks absorbing into same commit
- Prefer consolidated fixups
Example:
git absorb --one-fixup-per-commit --and-rebase
--squash / -s
Create squash commits instead of fixup commits.
When to use:
- Want to edit commit messages during rebase
- Need to document why changes were added
- Prefer squash over fixup in workflow
Example:
git absorb --squash --and-rebase
Note: When using this flag, all references to "fixup commits" should be read as "squash commits".
Advanced Matching Flags
--whole-file / -w
Match the first commit that touched the same file (not just the same lines).
When to use:
- Adding new functions to a file
- Changes don't overlap with existing lines
- Want to absorb into file's original commit
Warning: Use with care! This is less precise than line-based matching.
Example:
git absorb --whole-file
Information Flags
--verbose / -v
Display more detailed output about the absorption process.
When to use:
- Debugging unexpected behavior
- Understanding how changes are being matched
- Learning how git-absorb works
Example:
git absorb --verbose --dry-run
--version / -V
Display git-absorb version information.
git absorb --version
--help / -h
Display help information.
git absorb --help
Options
--message <MESSAGE> / -m <MESSAGE>
Use the same commit message body for all generated fixup commits.
When to use:
- Want consistent messaging across fixups
- Documenting a batch of related changes
- Organization requires specific commit formats
Example:
git absorb -m "Address PR review feedback" --and-rebase
-- <REBASE_OPTIONS>
Pass options to git rebase (must be last argument, requires --).
When to use:
- Need to pass specific rebase options
- Custom rebase behavior required
- Using with
--and-rebaseflag
Example:
git absorb --and-rebase -- --autostash
Note: Only valid when --and-rebase is used.
Advanced Patterns
Pattern 1: Large Feature Branch
Scenario: Working on a feature branch with 50+ commits
# Option 1: Use --base to specify range
git add <fixed-files>
git absorb --base main --and-rebase
# Option 2: Configure maxStack permanently
git config absorb.maxStack 100
git add <fixed-files>
git absorb --and-rebase
Pattern 2: Selective Absorption
Scenario: Only want to absorb specific files, not everything staged
# Stage only the files you want to absorb
git add file1.py file2.py
# Other staged files won't be absorbed
git absorb --and-rebase
Pattern 3: Review Before Committing
Scenario: Want to inspect fixup commits before rebasing
# Step 1: Create fixup commits (no rebase)
git absorb
# Step 2: Review what was created
git log --oneline -10
# Step 3: If satisfied, rebase manually
git rebase -i --autosquash main
# If not satisfied, reset
git reset --soft PRE_ABSORB_HEAD
Pattern 4: Team Branch with Multiple Authors
Scenario: Fixing bugs across a shared feature branch
# Allow absorbing into teammates' commits
git absorb --force-author --and-rebase
# Or configure permanently for this repo
git config absorb.forceAuthor true
git absorb --and-rebase
Pattern 5: Verbose Debugging
Scenario: Understanding why changes aren't absorbing
# Use verbose mode with dry-run
git absorb --verbose --dry-run
# Look for messages like:
# "Can't find appropriate commit for hunk..."
# "Stack limit reached..."
Pattern 6: Consolidate Multiple Hunks
Scenario: Many small fixes to the same commit, want one fixup
git absorb --one-fixup-per-commit --and-rebase
Pattern 7: Detached HEAD Workflow
Scenario: Working in detached HEAD state (cherry-pick, bisect, etc.)
git absorb --force-detach --and-rebase
Flag Combinations
Recommended Combinations
Safe exploration:
git absorb --dry-run --verbose
Aggressive auto-fix:
git absorb --force --and-rebase
Team branch cleanup:
git absorb --force-author --one-fixup-per-commit --and-rebase
Large feature branch:
git absorb --base main --verbose --and-rebase
Common Issues and Solutions
"Can't find appropriate commit"
Cause: Changes are too new or don't match any commits in range
Solutions:
# Increase range
git absorb --base main
# Check if file exists in commits
git log --oneline --follow <file>
# Consider if change belongs in new commit
"Stack limit reached"
Cause: Default 10-commit limit exceeded
Solutions:
# Use --base
git absorb --base main --and-rebase
# Or increase maxStack
git config absorb.maxStack 50
"Conflicts during rebase"
Cause: Changes can't be cleanly absorbed
Solutions:
# Abort and try manual approach
git rebase --abort
git reset --soft PRE_ABSORB_HEAD
# Or resolve conflicts manually
# (follow git's conflict resolution prompts)
Unintended absorption into wrong commit
Cause: git-absorb matched lines incorrectly
Prevention:
# Always use --dry-run first
git absorb --dry-run
# Review before rebasing
git absorb # no --and-rebase
git log --oneline -10 # review fixups
Recovery:
git reset --soft PRE_ABSORB_HEAD