krusty93/relego / .agents/skills/gh-stack
gh-stack
VerifiedManages stacked PRs and splits multi-part work into reviewable branches with gh-stack. Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout; when asked to split or isolate work for review; whenever a user mentions a stack, branch layers, dependent PRs, or gh stack; or when a stack is checked out.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| references/commands.md | markdown | 10.6 KB |
| references/stack-design.md | markdown | 4.1 KB |
| references/troubleshooting.md | markdown | 8.7 KB |
references/troubleshooting.md
View on GitHub# Troubleshooting and recovery
## Contents
- [Rebase conflicts (exit 3)](#rebase-conflicts-exit-3)
- [After a squash merge](#after-a-squash-merge)
- [Local and remote stacks have diverged](#local-and-remote-stacks-have-diverged)
- [Restructuring a stack](#restructuring-a-stack)
- [Branch belongs to several stacks (exit 6)](#branch-belongs-to-several-stacks-exit-6)
- [Driving stacks from another tool or worktree](#driving-stacks-from-another-tool-or-worktree)
- [Stack file is locked (exit 8)](#stack-file-is-locked-exit-8)
- [An interrupted modify session (exit 10)](#an-interrupted-modify-session-exit-10)
## Rebase conflicts (exit 3)
`rebase` and `sync` both exit 3 on conflict. `sync` restores every branch to its pre-rebase state
first, so a failed `sync` leaves nothing half-applied; a failed `rebase` stops mid-flight and waits.
```bash
gh stack rebase
# exit 3 — conflicted paths are listed on stderr
git add <resolved paths>
gh stack rebase --continue # repeat if the next branch also conflicts
```
`gh stack rebase --abort` restores every branch in the stack, not just the current one.
Because `init` enables `git rerere`, a conflict you resolve once is replayed automatically the next
time the same conflict appears — which is common, since a change low in the stack is rebased through
every branch above it. Without `rerere`, repeated conflicts may need manual resolution on each
affected layer.
## After a squash merge
A squash merge replaces the branch's commits with one new commit, so the originals no longer exist
in the trunk's history and an ordinary rebase would try to replay them again.
`gh stack sync` detects this and rebases with `--onto` against the correct target, skipping the
merged branch:
```bash
gh stack sync
gh stack view --json # merged branch reports "isMerged": true, "state": "MERGED"
```
No manual action is needed. If the replay conflicts, `sync` restores all branches and exits 3.
Run `gh stack rebase` to rerun the rebase, which will stop at the conflict and allow you to resolve
and then `--continue` until complete. Use `gh stack sync --prune` to also delete local branches for
merged PRs.
## Local and remote stacks have diverged
Divergence means the local stack and the stack on GitHub changed in different ways — for example
branches were added locally while a PR was added to the stack on github.com.
When non-interactive, `sync` prints both chains, changes nothing, and exits **0** with
`Sync aborted`. Success here does not mean the sync happened; check for that message, or re-run
`gh stack view --json` and compare.
Two resolution paths:
- **Keep the remote version.** Drop local tracking and pull the stack back down.
```bash
gh stack unstack --local # keeps the stack on GitHub
gh stack checkout <stack-number> # or a PR number
```
- **Keep the local version.** Remove the grouping on GitHub, then recreate it from local state.
```bash
gh stack unstack # removes the grouping; PRs and branches survive
gh stack submit --auto
```
Neither path deletes pull requests or branches.
Remote unstacking leaves PRs that are merging (auto-merge enabled) or are queued (in a merge queue)
stacked. If needed, clear that state before retrying.
## Restructuring a stack
There is no non-interactive reorder, rename, or removal. `add` run from the wrong branch suggests
`gh stack modify`, but that is TUI-only. Tear the stack down and rebuild it instead:
```bash
gh stack unstack # removes local tracking and the GitHub grouping
# Rename or drop branches, and rewrite ancestry as needed.
gh stack init --base main branch-1 branch-2 branch-3
gh stack submit --auto # re-link on GitHub
```
`init` adopts branches that already exist, so the rebuild reuses them rather than creating new ones.
Existing PRs survive. Once Git ancestry is correct, `submit` updates their base branches and
re-links the stack on GitHub.
Changing metadata does **not** change Git ancestry. Reorder commits first, then rebuild the stack.
For example, to change `main <- models <- migration <- ui` into
`main <- migration <- models <- ui`:
```bash
old_models=$(git rev-parse models)
old_migration=$(git rev-parse migration)
git rebase --onto main "$old_models" migration
git rebase --onto migration main models
git rebase --onto models "$old_migration" ui
gh stack unstack
gh stack init --base main migration models ui
```
The first rebase moves migration-only commits onto trunk, the second replays model commits above
them, and the third replays UI-only commits above models. Preserve the old boundary SHAs before
moving any branch. For a different reorder, identify each layer's range with
`git log <old-parent>..<branch>`, then replay the ranges bottom to top.
## Branch belongs to several stacks (exit 6)
Commands exit 6 when the current branch cannot identify a single stack — typically because it is the
trunk of more than one stack. There is no flag to disambiguate.
```bash
gh stack checkout <a-branch-unique-to-the-intended-stack>
```
Then rerun. Commands that take an explicit stack number (`merge 7`, `unstack 7`) sidestep the
problem entirely, since they do not infer the stack from the current branch.
## Driving stacks from another tool or worktree
`gh stack link` creates and updates stacks purely through the API, with no local tracking state.
Use it when branches are managed by jj, Sapling, git-town, or another external workflow that does
not use gh-stack's local catalog. Linked worktrees themselves are supported: they share
`<common-dir>/gh-stack` and do not require `link`.
```bash
gh stack link branch-a branch-b branch-c # bottom to top
gh stack link --base develop --open a b c # non-default trunk, ready for review
gh stack link 10 20 30 # by PR number
gh stack link 7 feature-d # append to existing stack #7
```
Because `link` writes no local state, the local navigation commands (`up`, `down`, `top`, `bottom`)
will not work on the result. Use `gh stack checkout <stack-number>` if you later want local tracking.
Git 2.36+ is required. Legacy worktree catalogs are consolidated automatically only when their
definitions agree or are disjoint; originals are preserved. On migration conflicts, reconcile the
reported source definitions rather than choosing the newest file. Finish legacy operations in
their original worktree first, and do not mix old and new gh-stack writers in one clone.
Navigation does not take over another worktree's checkout. Use `--print-path` with an explicit
target, check the exit status, and change directory to the quoted output. Only affected clean
owners are updated by rebase/sync; commit or stash manually when those owners are dirty. gh-stack
does not automatically stash or create/remove worktrees.
For `git init --separate-git-dir` repositories, main invocation and existing absolute/relative
`core.worktree` backlinks are supported, including settings in the main `config.worktree`. The
discovery caveat is only linked invocation without a main-worktree backlink. A required unresolved
main owner produces actionable guidance to run from the main worktree or supply the backlink;
unaffected worktrees continue. Never navigate to an administration directory or guess its checkout.
Existing backlinks are read without adding a private registry or changing Git configuration.
## Stack file is locked (exit 8)
Another `gh stack` process holds either the short catalog lock (`<common-dir>/gh-stack.lock`) or
the clone-wide mutation lock (`<common-dir>/gh-stack-operation.lock`). Wait and retry; read-only
views remain available. Do not delete lock files to bypass coordination. Paused operations are
also guarded by shared recovery journals after their process lock has been released.
## An interrupted modify session (exit 10)
`gh stack modify` is TUI-only and should never be invoked by an agent. If a repository is left in
this state by someone else, restore it:
```bash
gh stack modify --abort
```
Related: `submit` also detects a pending modify state, and under a TTY asks before overwriting the
matching stack on GitHub with local state. An unrelated stack cannot consume or clear that journal.
Modify supports stacks distributed across worktrees, but agents must still not launch its TUI.
Renames, fold-down cherry-picks, and rebases execute in the appropriate clean owners; only the
origin switches for unoccupied branches. Drop/fold sources and their worktrees remain intact.
Resolve and stage in the worktree reported by the conflict, then invoke `modify --continue` from
any linked worktree. A later conflict can be in a different owner. Abort reverses owner-local
renames, restores only operation-touched refs, and deletes only proven operation-created refs,
never worktrees. Missing owners, externally changed refs, or save failures retain the journal.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |