| name | troubleshoot-worktree |
| description | Troubleshoot git worktree, branch, and refname issues |
Git Worktree Troubleshooting
Diagnose and fix worktree, branch, and reference issues.
Quick Diagnostics
Always run first:
git worktree list
git branch -a
git status
pwd
Worktree Discovery
Never assume paths - always discover with git worktree list. The first
column is the path; the bracketed name is the branch checked out there.
Critical: Ambiguous Refname
Warning: warning: refname 'origin/main' is ambiguous
Means TWO things named origin/main:
refs/heads/origin/main - LOCAL branch (bad)
refs/remotes/origin/main - remote tracking (good)
Diagnose: git show-ref origin/main
Fix: git branch -D origin/main then verify only 1 line remains with git show-ref origin/main.
The same ambiguity can occur for any branch name, not just main — on a
git-flow repo (default branch develop) watch for origin/develop too.
Substitute the branch name in the diagnose/fix commands above.
Common Errors
Branch Not Found
git fetch origin --force
git branch -a | grep -i "<branch>"
Uncommitted Changes
git add . && git commit -m "WIP"
git stash push -m "before operation"
git checkout -- .
Embedded Git Repository
git rm --cached <folder>
echo "<folder>/" >> .gitignore
Related Skills
- troubleshoot-rebase (git-workflows) — Diagnose and recover from git rebase failures
- troubleshoot-precommit (git-workflows) — Troubleshoot pre-commit hook failures
- refresh-repo (github-workflows) — Full repo sync including worktree cleanup