GitButler Stacks

Dependent branches → anchor-based stacking → reviewable chunks.

<when_to_use>

Sequential dependencies (e.g., refactor → API → frontend)
Large features broken into reviewable chunks
Granular code review (approve/merge early phases independently)
Post-hoc stack organization after exploratory coding

NOT for: independent parallel features (use virtual branches), projects using Graphite stacking

</when_to_use>

Stacked vs Virtual Branches

Type	Use Case	Dependencies
Virtual	Independent, unrelated work	None — parallel
Stacked	Sequential dependencies	Each builds on parent

Stacked branches = virtual branches split into dependent sequence. Default: Virtual branches are stacks of one.

Creating Stacks

# Base branch (no anchor)
but branch new base-feature

# Stacked branch (--anchor specifies parent)
but branch new child-feature --anchor base-feature

# Third level
but branch new grandchild-feature --anchor child-feature

Result: base-feature ← child-feature ← grandchild-feature

Short form: -a instead of --anchor

but branch new child -a parent

Stack Patterns

Common patterns: feature dependency chains, refactoring sequences, deep stacks.

Example - Feature Dependency:

but branch new auth-core
but branch new auth-oauth --anchor auth-core
but branch new auth-social --anchor auth-oauth

See references/patterns.md for detailed patterns with commit examples.

Post-Hoc Stack Organization

Convert independent branches into a stack by recreating with correct anchors:

Create new branch with --anchor pointing to intended parent
Move commits with but rub <sha> <new-branch>
Delete original branch

See references/reorganization.md for detailed workflows.

Publishing Stacks

Using CLI (Preferred)

# Push and create PR for a branch
but push dependent-feature
but pr new dependent-feature

# Push all unpushed branches
but push

but push + but pr new handles:

Pushing branches to remote
Creating PRs with correct base branches
Updating existing PRs if already created

Using GitHub CLI (Alternative)

# Push branches
git push -u origin base-feature
git push -u origin dependent-feature

# Create PRs with correct base branches
gh pr create --base main --head base-feature \
  --title "feat: base feature" \
  --body "First in stack"

gh pr create --base base-feature --head dependent-feature \
  --title "feat: dependent feature" \
  --body "Depends on base-feature PR"

GitHub Settings

Enable automatic branch deletion after merge
Use Merge strategy (recommended) — no force pushes needed
Merge bottom-to-top (sequential order)

Conflict Handling in Stacks

GitButler resolves conflicts per-commit during rebase:

When base branch updates, dependent commits rebase automatically
Conflicted commits marked but don't block other commits
Resolve conflicts per affected commit
Partial resolution can be saved and continued later

# Update base (may trigger rebases in stack)
but pull

# Check which commits have conflicts
but status

# Resolve in editor, GitButler auto-detects resolution

Unlike git rebase: Remaining commits continue rebasing even if some conflict.

Stack Reorganization

Key operations for restructuring stacks:

Operation	Command
Squash commits	`but squash <branch>` or `but rub <newer> <older>`
Move commit	`but rub <sha> <target-branch>`
Split branch	Create anchored branch, move commits

See references/reorganization.md for detailed examples.

Stack Navigation

Note: Virtual branches don't need checkout — all branches active simultaneously.

# View full stack structure
but status

# Work on any branch directly (no checkout needed)
but commit base-feature -m "update base"
but commit dependent-feature -m "update dependent"

# Inspect a specific branch
but show dependent-feature

# JSON for programmatic analysis
but show dependent-feature --json | jq '.commits[] | .id'

ALWAYS:

Create stacks with --anchor from the start
Merge stacks bottom-to-top (base first, dependents after)
Snapshot before reorganizing: but oplog snapshot --message "Before stack reorganization"
Keep each level small (100-250 LOC) for reviewability
Delete empty branches after reorganization

NEVER:

Skip stack levels when merging
Stack independent, unrelated features (use virtual branches)
Create deep stacks (5+ levels) without good reason
Forget anchor when creating dependent branches

Troubleshooting

Symptom	Cause	Solution
Stack not showing in `but status`	Missing `--anchor`	Recreate with correct anchor
Commits in wrong stack level	Wrong branch targeted	`but rub <sha> correct-branch`
Can't merge middle of stack	Wrong order	Merge bottom-to-top only

Recovery

To fix a branch with wrong/missing anchor: create new branch with correct anchor, move commits with but rub, delete original.

See references/reorganization.md for complete recovery procedures.

Best Practices

Planning

Start simple: 2-3 levels max initially
Single responsibility per level
Only stack when there's a real dependency

Maintenance

Run but status regularly to verify structure
Commit to correct branches immediately
Clean up empty branches

Communication

Clear commit messages explaining why stack level exists
Descriptive names indicating stack relationship
Share but status when coordinating

Reference Files

references/patterns.md — Detailed stack patterns (feature dependency, refactoring, deep stacks)
references/reorganization.md — Post-hoc organization, squashing, moving commits, splitting

Related Skills

gitbutler-virtual-branches — Core GitButler workflows
gitbutler-complete-branch — Merging to main
gitbutler-multi-agent — Multi-agent coordination

gitbutler-stacks