GH stacks should be worktree friendly

[sorinlg]

Given my first experience with GH Stacks, I found myself hitting a proverbial wall when trying to incorporate it into my worktree-based workflow.

With a single repository checkout, the quick start documentation describes a straightforward and pleasant experience. However, things become much less smooth when using Git worktrees.

From what I can tell, the GH Stacks metadata is scoped to the worktree where the stack was created, rather than to the repository as a whole. As a result, other worktrees in the same repository cannot see or operate on that stack.

My primary use case is splitting a larger feature into multiple dependent PRs. While an AI agent is implementing or troubleshooting the first PR, I’d like to begin working on the next piece in a separate worktree. Unfortunately, because Git prevents a branch from being checked out in multiple worktrees simultaneously, any gh stack rebase or similar operation requires me to pause work, detach the affected branches from their worktrees, perform the stack operation, and then restore the worktrees before I can continue.

I may be missing an intended workflow, but this feels like an unnecessary limitation of an otherwise excellent tool. It seems these issues could largely disappear if the GH Stacks metadata lived at the repository level (for example, in the shared Git directory used by all worktrees), allowing the gh stack CLI to resolve and operate on the same stack regardless of which worktree it is invoked from, similar to how Git itself treats worktree-aware repository state.

[russell-dot-js]

Similar experience! Loving github stacks, but need to frequently detach branches from worktrees as part of the stack management workflow

[samdalton]

Yep just hit this when rebasing a conflict. I directed agent (Fable) to break work into separate worktrees while using gh stack to compile the final deliverable. Since each branch was in a separate worktree, this is what happened:

> gh stack checkout 1636
✓ Local stack matches remote — switching to branch (stack #1636)
ℹ Already on 2367-s5-web-ui
Stack: (main) <- 2367-s3-planfor <- s1-engine <- 2367-s2-quadstate <- 2367-s4-rewire <- 2367-s5-web-ui
> gh stack rebase
✓ Fetched origin
⚠ Trunk main has diverged from origin — skipping trunk update
  Local and remote main have diverged. Resolve manually.
Stack detected: (main) <- 2367-s3-planfor <- s1-engine <- 2367-s2-quadstate <- 2367-s4-rewire <- 2367-s5-web-ui
Rebasing branches in order, starting from 2367-s3-planfor to 2367-s5-web-ui
✗ checking out 2367-s3-planfor: failed to run git: fatal: '2367-s3-planfor' is already used by worktree at '/private/tmp/2367-s3-planfor'

 

[cbejensen]

Just installed the stack CLI extension to try it out after realizing I needed to make a change at trunk. Only had 2 branches, each in separate worktrees. As soon as I ran gh stack bottom on the leaf branch I got failed to run git: fatal: <branch> is already used by worktree at <path>.

[stefco]

+1 and seems like an extremely straightforward fix (which i already have our LLM harness do manually): have gh do the rebase in the worktree dir if it exists. i do this daily with my own script.

[tkindy]

I think there's two requests bundled up in this one discussion, and most people are talking about one of them (gh stack working with branches in the stack that are checked out in other worktrees).

I want to make sure to also call out the other piece of OP's post, which is more blocking for my workflow:

From what I can tell, the GH Stacks metadata is scoped to the worktree where the stack was created, rather than to the repository as a whole. As a result, other worktrees in the same repository cannot see or operate on that stack.

This is really unintuitive to me. My workflow involves keeping a set of worktrees for a repo around indefinitely (as a cache, avoiding the lengthy worktree setup time to install deps from scratch, etc.), and I check out branches into them as needed. As I understand it, this isn't an uncommon workflow in the age of running multiple parallel AI agents in the same repo. The fact that stacks only exist in the worktree they were defined in is therefore workflow-breaking for me.

To be concrete, here's a sequence of commands operating on two worktrees, my-repo and my-repo2, for the same repo:

$ cd my-repo
$ gh stack init stack-base
$ gh checkout -
$ cd ../my-repo2
$ gh checkout stack-base
$ gh stack view

I'd expect gh stack view to understand that I'm on the stack I initialized with stack-base as the base in the my-repo worktree. However, today, that gives me an error:

$ gh stack view
✗ current branch "stack-base" is not part of a stack
Checkout an existing stack using `gh stack checkout` or create a new stack using `gh stack init`

This means I always have to work with a stack in the same worktree I created it in, which doesn't fit well with my workflow. I really need stacks to be stored at the repo level on my machine, not at the worktree level.