Skip to content

feat(cli): link gh-stack worktrees and check them in doctor - #67

Open
lettertwo wants to merge 9 commits into
gh-stack-read-pathfrom
gh-stack-linking-doctor
Open

feat(cli): link gh-stack worktrees and check them in doctor#67
lettertwo wants to merge 9 commits into
gh-stack-read-pathfrom
gh-stack-linking-doctor

Conversation

@lettertwo

@lettertwo lettertwo commented Aug 28, 2026

Copy link
Copy Markdown
Owner

gh stack writes one JSON file per git dir, which for a linked worktree is
<common-dir>/worktrees/<name>/gh-stack. A stack created in one worktree is invisible from every
other one, which breaks list, routing, and changeset assembly. Upstream's own
skills/gh-stack/SKILL.md says the local file "would be wrong or absent" for worktree workflows.

This PR makes <common-dir>/gh-stack the one canonical store, with link_worktree symlinking
gh-stack and gh-stack.lock into each worktree's admin dir. gh-stack-rebase-state and
gh-stack-modify-state stay per-worktree, since sharing them would make every other worktree
believe it is mid-rebase. migrate_worktree moves a pre-existing real file into canonical with a
backup, and doctor --fix calls it.

doctor gains GhStackWorktreeNotLinked, GhStackDivergentStacks, GhStackNotInitialized,
GhStackExtensionNotFound, GhStackFileUnreadable, GhStackLocked, and BothStackToolsDetected.
The Graphite-specific stack errors become provider-neutral.

docs/adr/028-provider-neutral-stack-metadata.md covers why the symlinks work and why
read_metadata keeps a union fallback for worktrees that drift out of the linked state, under "The
shared canonical file" and the two sections after it. The claims about upstream's Save and Lock
are quoted there with file references.

Acceptance-tested against a copy of this repo's real 33-branch gh-stack file: doctor --fix
migrated it preserving all 33 branches, every base SHA, the trunk, and repository, and
gh stack view --json then parsed the workon-written file from two worktrees.

Testing: 630 tests, clippy clean.


Stack created with GitHub Stacks CLIGive Feedback 💬

@lettertwo lettertwo changed the title gh stack linking doctor feat(cli): link gh-stack worktrees and check them in doctor Aug 28, 2026
@lettertwo
lettertwo force-pushed the gh-stack-linking-doctor branch from 1d9562d to eb21ab1 Compare August 28, 2026 03:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant