[Bug]: a stray .DS_Store in .git/worktrees makes every gh stack command fail #587
Description
Describe the bug
A regular file inside .git/worktrees/ makes every gh stack command fail. On macOS, Finder drops a .DS_Store there as soon as someone opens the directory, so a repo that uses worktrees can end up with one without anyone noticing.
From the error, the state migration treats every entry of .git/worktrees/ as a worktree admin dir and gives up on the first one that isn't a directory. Skipping non-directories there would be enough.
Affected command
gh stack link (also gh stack view, gh stack add)
gh-stack version
gh stack version 0.2.1
GitHub CLI version
gh version 2.102.1 (2026-10-20)
Operating system
macOS 27.0.1
Shell
zsh
Steps to reproduce
git init -b main repo && cd repo
git commit --allow-empty -m init
git worktree add ../wt -b feature
touch .git/worktrees/.DS_Store
gh stack view
gh stack add test-branchNo remote is needed. I hit it on a real repo first, running gh stack link over three pushed branches.
Expected behavior
Files that aren't directories in .git/worktrees/ are skipped, and the command runs.
Actual behavior
The command fails before it does anything. Removing the .DS_Store fixes it.
Terminal output
$ gh stack view
✗ checking legacy stack state: worktree administration path "/…/repo/.git/worktrees/.DS_Store" is not a directory
$ gh stack add test-branch
✗ migrating stack state: worktree administration path "/…/repo/.git/worktrees/.DS_Store" is not a directory
Preflight checks
- I searched the existing issues for duplicates.
- I ran
gh extension upgrade stackand reproduced this issue on the latest stable release.
— printed by Claude Code, signed by me.
Activity
Lushiyao5 commentedon Oct 27, 2026
I dug into this while working on a fix — the root cause is in the legacy state migration:
legacyCatalogsininternal/stack/migration.gotreats every entry of.git/worktrees/as a worktree administration directory and fails on the first entry that is not one (worktree administration path %q is not a directory). Any stray file dropped there — for example the.DS_Storethat Finder creates the moment the directory is opened on macOS — makes everygh stackcommand fail until it is removed by hand.A fix is prepared and verified at
Lushiyao5/gh-stack@b6081e2(branchfix/skip-stray-worktree-admin-files):defaultOps.worktreeGitDirsalready treats the same directory;TestLegacyState_MetadataErrorsis updated accordingly andTestLegacyState_SkipsStrayFilesInAdministrationDirectorycovers both a stray file alone and a stray file alongside a migratable catalog;main, confirmed fixed after the change;go vet ./...and theinternal/stacksuite pass.I attempted to open a pull request, but this repository limits pull requests to collaborators. Happy to open one if that ever changes — otherwise please feel free to take the branch directly.