GitButler Stack Workflows

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>

<stack_vs_virtual>

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.

</stack_vs_virtual>

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

Feature Dependency Stack

Auth foundation

but branch new auth-core but commit auth-core -m "feat: add authentication core"

OAuth layer depends on auth core

but branch new auth-oauth --anchor auth-core but commit auth-oauth -m "feat: add OAuth integration"

Social login depends on OAuth

but branch new auth-social --anchor auth-oauth but commit auth-social -m "feat: add social login"

Refactoring Stack

Extract utilities

but branch new refactor-extract-utils but commit refactor-extract-utils -m "refactor: extract common utilities"

Update consumers

but branch new refactor-use-utils --anchor refactor-extract-utils but commit refactor-use-utils -m "refactor: use extracted utilities"

Clean up

but branch new refactor-cleanup --anchor refactor-use-utils but commit refactor-cleanup -m "refactor: remove deprecated code"

Deep Stack (5 levels)

but branch new db-schema but branch new data-access --anchor db-schema but branch new business-logic --anchor data-access but branch new api-endpoints --anchor business-logic but branch new frontend-integration --anchor api-endpoints

<post_hoc>

Post-Hoc Stack Organization

Problem: Created branches independently, now want to stack them.

Solution: Recreate with correct anchors:

Current: three independent branches

feature-a, feature-b, feature-c

Stack feature-b on feature-a

but branch new feature-b-stacked --anchor feature-a commit_sha=$(but log | grep "feature-b:" | head -1 | awk '{print $1}') but rub $commit_sha feature-b-stacked but branch delete feature-b --force

Stack feature-c on feature-b-stacked

but branch new feature-c-stacked --anchor feature-b-stacked commit_sha=$(but log | grep "feature-c:" | head -1 | awk '{print $1}') but rub $commit_sha feature-c-stacked but branch delete feature-c --force

</post_hoc>

<pr_workflow>

PR Preparation for Stacks

GitButler CLI lacks native PR submission. Use GitHub CLI:

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)

</pr_workflow>

Stack Reorganization

Squashing Within Stack

newer_commit=$(but log | grep "newer" | awk '{print $1}') older_commit=$(but log | grep "older" | awk '{print $1}') but rub $newer_commit $older_commit

Moving Commits Between Stack Levels

commit_sha=$(but log | grep "specific commit" | awk '{print $1}') but rub $commit_sha correct-branch

Splitting a Branch

Original has multiple features

but branch new second-feature --anchor original-branch commit_sha=$(but log | grep "second feature commit" | awk '{print $1}') but rub $commit_sha second-feature

Stack Navigation

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

View full stack structure

but log

Work on any branch directly (no checkout needed)

but commit base-feature -m "update base" but commit dependent-feature -m "update dependent"

JSON for programmatic analysis

but --json log | jq '.[] | .branchDetails[] | {name, baseCommit}'

ALWAYS:

• Create stacks with --anchor from the start

• Merge stacks bottom-to-top (base first, dependents after)

• Snapshot before reorganizing: but 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

Common Issues

Symptom Cause Solution

Stack not showing in but log

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

Recreate branch with correct anchor

but branch new child-stacked --anchor parent commit_sha=$(but log | grep "child:" | head -1 | awk '{print $1}') but rub $commit_sha child-stacked but branch delete child --force

<best_practices>

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 log 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

</best_practices>

• version-control skill — core GitButler workflows

• complete-branch skill — merging to main

• multi-agent skill — multi-agent coordination

• GitButler Stacks Docs