Graphite Stacks

Trunk-based development with stacked PRs using Graphite CLI.

<when_to_use>

• Creating or managing branch stacks

• Submitting stacked PRs

• Reorganizing branch relationships

• Addressing PR feedback across a stack

• Recovering from stack corruption

• Any gt command usage

</when_to_use>

Core Principle

Use gt commands exclusively. Mixing git and gt causes sync issues and divergent stacks. The only exception: git add for staging (or use -a flags).

This, Not That

Task This Not That

Create branch gt create 'name' -am "msg"

git checkout -b name

Commit changes gt modify -acm "msg"

git commit -m "msg"

Push to remote gt submit

git push

Rebase stack gt restack

git rebase

View stack gt status or gt ls

git log --graph

Switch branches gt checkout

git checkout

Amend commit gt modify -a

git commit --amend

Multi-PR feedback gt top && gt absorb -a

Cherry-pick commits manually

Stack Lifecycle

Create stack → Implement features → Submit PRs → Address feedback → Merge │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ gt create gt modify -acm gt submit gt absorb gt sync

Creating Stacks

New branch with staged changes

gt create 'feature/step-1' -am "feat: first step"

Continue stacking

gt create 'feature/step-2' -am "feat: second step" gt create 'feature/step-3' -am "feat: third step"

Insert branch between current and child

gt create 'feature/step-1.5' --insert -am "feat: inserted step"

Navigation

Command Action

gt up

Move up the stack (toward children)

gt down

Move down the stack (toward parent)

gt top

Jump to stack top

gt bottom

Jump to stack bottom

gt checkout

Interactive branch picker

Modifying Branches

Amend current branch (stages all)

gt modify -a

New commit within same branch

gt modify -acm "fix: address review feedback"

Commit to a different branch in the stack

git add path/to/file.ts gt modify --into target-branch -m "feat: add file"

ALWAYS:

• Use gt create for new branches

• Use gt modify for commits

• Use gt submit to push

• Use gt restack after parent changes

• Check gt status when uncertain

NEVER:

• Mix git commit/push/rebase with gt workflows

• Force push without understanding stack state

• Use git rebase -i (breaks Graphite metadata)

Addressing Review Feedback

Single PR: Navigate to branch, modify directly

gt checkout target-branch gt modify -acm "fix: address review comment" gt submit

Multiple PRs in stack: Use absorb from top

gt top git add . gt absorb -a gt submit --stack

Graphite routes changes to correct branches based on file history.

Reorganizing Stacks

Move branch to different parent

gt move --onto new-parent

Move specific branch

gt move --source branch-name --onto target

After reorganization

gt restack

Submitting

Current branch + downstack

gt submit

Entire stack

gt submit --stack

Non-interactive (automation)

gt submit --no-interactive

Stack Visualization

JSON with parent relationships (preferred for scripts)

gt status

Visual tree

gt ls

Recent history

gt log

Sync and Maintenance

Pull trunk, rebase stacks, clean merged

gt sync

Rebase branches onto updated parents

gt restack

Undo last gt operation

gt undo

When Things Go Wrong

Stack corruption symptoms:

• Branches appear as siblings instead of parent-child

• PRs contain wrong files

• gt status shows unexpected structure

See recovery.md for step-by-step recovery procedures.

• commands.md - Quick command reference

• recovery.md - Stack corruption recovery