Ghstack Workflow

ghstack + jj: Stacked PR Workflow

Manage stacked pull requests using ghstack (or gh stack) with Jujutsu (jj) as the local VCS. Each commit becomes exactly one PR.

Core Concept

1 commit  ==  1 PR
N commits ==  N PRs  (called a "stack")

Each PR's base is the commit below it. Reviewers see only that layer's diff. The bottom PR targets main (or trunk).

commit-3  -> PR #3 (base: commit-2)   PR #2 (base: commit-1)
commit-1  -> PR #1 (base: main)      //base`, `gh///head`, `gh///orig`.

## Workflow: Update a PR in the Stack

```bash
# 1. Edit files as needed
# 2. Squash changes into the TARGET commit (NOT a new commit)
jj squash -r 
# 3. Resubmit the entire stack
ghstack

Critical: Use jj squash (not jj commit) to amend an existing commit. This preserves the 1-commit-1-PR mapping.

Targeting a specific commit

# Squash working copy into a specific revision
jj squash -r 

# Or squash a specific revision into another
jj squash  -d 

Workflow: Land (Merge) a Stack

# Land a specific PR (cascading rebase + merge)
ghstack land 
# OR: ghstack land #
# OR: gh stack merge 

Never use gh pr merge or the GitHub UI merge button on a ghstack PR. This breaks the stack's base branch tracking and produces [ghstack-poisoned] commits.

Workflow: Rebase a Stack onto Updated Main

# Fetch latest main, then rebase the entire stack
jj rebase -d main
# Then resubmit
ghstack

Never git merge into a ghstack branch — ghstack will error because each commit must remain a separate PR.

Workflow: Checkout an Existing Stack

# By PR number
ghstack checkout 
# OR: gh stack checkout 

Workflow: Sync PR Descriptions

# Sync GitHub PR descriptions back to local commit messages
ghstack sync

Branch Structure (Internal)

For each commit N in a stack, ghstack creates three branches:

| Branch | Purpose | | ---------------- | --------------------------------------------------------- | | gh/user/N/base | Base branch (like main). Never force-pushed. | | gh/user/N/head | The actual change. PR targets base. Never force-pushed. | | gh/user/N/orig | Exact local commit. Not visible on GitHub. |

Pitfalls

1. Never gh pr merge on a ghstack PR. Always use ghstack land. The UI

merge button breaks base branch tracking.

1. Never force-push ghstack branches manually. ghstack manages branch

pointers. Manual force-poisoning corrupts the stack.

1. Never git merge into a ghstack branch. Use jj rebase instead. Merge

commits break the 1-commit-1-PR invariant.

1. Use jj squash not jj commit for updates. A new commit means a new PR.

Squashing preserves the existing PR.

1. Rebase before resubmit. If main has moved, rebase your stack first:

jj rebase -d main then ghstack.

1. Stack order matters. Commits are stacked in topological order (oldest =

bottom). Reorder with jj rebase -r -d before submitting.

1. ghstack vs gh stack: ghstack (ezyang) is the Python CLI with

~/.ghstackrc. gh stack (GitHub official) is a Go-based gh extension with .git/gh-stack metadata. They are NOT compatible — pick one per repo.

1. Splitting a stack into separate PRs. When asked to split changes into

individual PRs (1 commit == 1 PR), use ghstack submit for each commit. If ghstack submit fails mid-stack (e.g., timeout, duplicate commit error), push remaining commits as separate branches and create PRs manually:

``bash # Push each commit to its own branch git push origin :refs/heads/fix/ # Create PRs manually, basing each on the previous PR's head branch gh pr create --title "..." --head fix/ --base ``

This preserves the stack relationship without relying on ghstack's internal tracking.

Quick Reference

| Task | Command | | ----------------- | --------------------------------------- | | Create stack | jj commit -m "..." x N → ghstack | | Update PR | edit → jj squash -r → ghstack | | Land PR | ghstack land | | Rebase stack | jj rebase -d main → ghstack | | Checkout PR | ghstack checkout | | Sync descriptions | ghstack sync | | View stack | jj log -r main..@ |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shikanime-labs
• Source: shikanime-labs/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.