Renaming a stacked branch with `git branch -m` strands the stack: metadata keeps the old name

[jiku0730]

Summary

gh stack matches the current branch against .git/gh-stack by exact string
(resolveStack → FindAllStacksForBranch → Stack.Contains, cmd/utils.go:395,
internal/stack/stack.go:241). Renaming a stacked branch with git branch -m is not
observed, so the stack file keeps pointing at a name that no longer exists and every
stack command bails out with the same generic message.

gh stack modify already renames a branch in git and in the stack file together
(internal/modify/apply.go:190-228, verified: both .git/gh-stack and the git branch are
updated), so the invariant is understood. This issue is about a rename performed outside
gh-stack, which is how most people rename a branch.

Related but distinct: #137 reaches the same stranded state through sync --prune
(branch deleted, stack entry left behind), and #193 is the same family of "git operations
performed outside gh-stack aren't observed".

Reproduction

Requires an origin remote, but the repository need not exist.

git init repro && cd repro
git commit --allow-empty -m initial
git remote add origin https://github.com/you/does-not-exist.git
git switch -c feat/test
git commit --allow-empty -m wip

gh stack init feat/test      # ✓ Adopted 1 branch: main ← feat/test
gh stack view --short        # ✓ works

git branch -m feat/test-1

gh stack view                # ✗ broken from here on

gh stack init with no arguments errors with "interactive input required", so the branch
name is passed explicitly to keep the repro scriptable.

Observed

.git/gh-stack is byte-identical before and after the rename; it still records
"branch": "feat/test".

Command	Output
gh stack view	✗ current branch "feat/test-1" is not part of a stack
gh stack add feat/test-2	same
gh stack unstack / unstack --local	same
gh stack checkout feat/test (old name)	✗ failed to checkout feat/test: failed to run git: error: pathspec 'feat/test' did not match any file(s) known to git
gh stack checkout feat/test-1 (new name)	✗ no locally tracked stack found for "feat/test-1"

gh stack unstack <n> --local would remove the entry, but a stack that has not been
submitted has no stack number (Number int \json:"number,omitempty"``,
internal/stack/stack.go:46), so it cannot be targeted:

$ gh stack unstack 1 --local
✗ stack #1 is not tracked locally

With no gh stack list (#150) and an interactive-only checkout picker, the ways out are
renaming the branch back (verified: this fully restores the stack) or editing
.git/gh-stack by hand.

Expected

1. Diagnose instead of denying. Before printing "is not part of a stack"
   (cmd/utils.go:234-243), check whether a recorded stack references a branch that no
   longer exists. git.BranchExists is already used throughout (cmd/sync.go:413,
   cmd/modify.go:315, …). checkout should also stop surfacing git's raw
   pathspec ... did not match error.

2. Leave an escape hatch. Removing or repairing a stack whose branches are missing
   should not require a stack number — this is the part gh stack sync --prune for a completed stack deletes the branch but leaves stack in gh stack checkout metadata #137 also runs into.

3. Offer to repair. git records the rename in the reflog:

   feat/test-1@{0}: Branch: renamed refs/heads/feat/test to refs/heads/feat/test-1
   

   so the stack file can be updated after confirming with the user. Reflog entries expire,
   so this complements 1 rather than replacing it.

I have a patch implementing 1 and 3 and will open a PR referencing this issue.

Environment

• gh stack v0.1.0
• macOS 24.6.0 (Darwin, arm64)

[jiku0730]

I have a patch for this, but this repository does not accept pull requests from forks (CreatePullRequest is denied for non-members), so I cannot open one. The branch is pushed to a fork and the diff is here:

main...jiku0730:gh-stack:fix/detect-external-branch-rename

Problem

The stack file records branch names, so git branch -m leaves .git/gh-stack pointing at
a name that no longer exists. Every command that resolves the current branch through
loadStack then reports current branch "..." is not part of a stack, with nothing to
suggest that a rename is the cause.

gh stack modify already renames a branch in git and in the stack file together
(internal/modify/apply.go:190-228). A rename performed with git alone has no such path,
and a stack that has not been submitted has no stack number, so unstack <n> --local
cannot remove the stale entry either.

Change

When the current branch is not part of a stack, walk its reflog for the names it
previously held. If a previous name is still recorded in the stack file and no longer
exists in git, offer to point the stack at the current name:

⚠ Branch "feat/test" in the stack no longer exists.
"feat/test-1" appears to be the same branch, renamed outside gh-stack.
? Update the stack to use "feat/test-1" instead of "feat/test"? (Y/n)

The hook is in loadStack, so view, add, push, submit, merge, sync, rebase,
switch, and unstack all recover through the same path.

Details worth reviewing:

• Confirmation is required. Without a terminal (and without ConfirmFn), the stack
  file is left alone and the cause and remedies are printed instead, so scripts and CI
  never have their state rewritten unattended.
• Repeated renames. BranchRenameHistory follows the reflog chain, so a → b → c
  reports ["b", "a"] and a stack still recording a is recovered.
• A recreated old branch is left alone. If the old name exists in git again, the stack
  entry refers to something real and is not redirected.
• All stacks follow. A rename is a fact about the branch, so every stack recording the
  old name is updated, and resolution then goes through the existing disambiguation in
  resolveStack. The trunk is handled the same way.
• Expired reflog. When the rename cannot be reconstructed, the error now names the
  recorded branches that no longer exist, instead of only saying the current branch is not
  part of a stack. This also covers the state reached in gh stack sync --prune for a completed stack deletes the branch but leaves stack in gh stack checkout metadata #137.

Tests

cmd/rename_recovery_test.go covers recovery through loadStack for a branch and for the
trunk, the declined case, the no-terminal case, a recreated old branch, and the expired
reflog message; each case asserts against the stack file on disk, not only the in-memory
stack. internal/git/rename_history_test.go exercises BranchRenameHistory against real
repositories, including a branch renamed twice.

go vet ./... and go test -race -count=1 ./... pass.

Manually verified end to end with a local build: the non-interactive path exits 2 without
touching .git/gh-stack, and the prompt appears as shown above. Driving the confirmation
itself under a pty is not automated here, since the prompter blocks on a terminal cursor
query; the confirmed path is covered by the unit tests via ConfirmFn, matching how the
existing confirmation prompts in this repo are tested.