A restricted fetch refspec also blocks checking out an existing remote branch, with an error that reads as 'branch does not exist'

[dmccoystephenson]

Problem

The generated-skill template's Edge cases section already documents that a
gardener-managed or otherwise restricted clone can carry a fetch refspec covering
the default branch only:

gh pr create fails with "you must first push the current branch to a remote"
despite a successful git push -u: the clone's fetch refspec may be
restricted to the default branch only … confirm with
git config --get-all remote.origin.fetch.

That entry covers the outbound consequence — creating a PR for a branch this
clone has just pushed. The same refspec has an inbound consequence the template
does not mention: an existing remote branch cannot be checked out by name.

In such a clone, git fetch origin <branch> succeeds and writes FETCH_HEAD, but
creates neither a local branch nor a remote-tracking ref, because the configured
refspec does not map refs/heads/<branch> anywhere. The subsequent
git checkout <branch> then has no DWIM candidate to resolve and fails with a
message that misdescribes the situation entirely:

error: pathspec '<branch>' did not match any file(s) known to git

Read literally, that says the branch does not exist — which invites either
re-fetching, or concluding the branch is gone and starting fresh work. Both are
wrong. The branch exists on the remote and was just fetched successfully; only
the mapping into a local ref is missing. The explicit refspec form
git fetch origin <branch>:<branch> creates the local branch directly and makes
the checkout succeed.

This matters most in exactly the case that produced it: resuming an interrupted
run's PR branch. Phase 1's carried-over-PR handling assumes the branch can be
checked out, and the first command of the cycle is where a misread of this error
does the most damage.

Observed instance

Stephenson-Software/create-dev-loop, gardener-managed clone. Confirmed:

$ git config --get-all remote.origin.fetch
+refs/heads/main:refs/remotes/origin/main

$ git fetch origin fix/phase-8-verification-and-merge-precedence && git checkout fix/phase-8-verification-and-merge-precedence
 * branch            fix/phase-8-verification-and-merge-precedence -> FETCH_HEAD
error: pathspec 'fix/phase-8-verification-and-merge-precedence' did not match any file(s) known to git

$ git fetch origin fix/phase-8-verification-and-merge-precedence:fix/phase-8-verification-and-merge-precedence
 * [new branch]      fix/phase-8-verification-and-merge-precedence -> fix/phase-8-verification-and-merge-precedence

Suggested direction

Extend the existing restricted-refspec Edge cases entry rather than adding a
second one next to it — one refspec, two symptoms, and a reader who hits either
symptom should find both. Suggested addition:

The same restricted refspec blocks checking an existing remote branch out by
name: git fetch origin <branch> writes only FETCH_HEAD, so
git checkout <branch> fails with error: pathspec '<branch>' did not match any file(s) known to git — which reads as "the branch does not exist" and is
not that. Use the explicit refspec git fetch origin <branch>:<branch>, which
creates the local branch directly. This is the form Phase 1 needs when resuming
a carried-over PR's branch.

Retitling the entry so it is findable from either symptom would help, since it is
currently indexed under the gh pr create error message alone.

Research grounding

No RESEARCH.md finding applies, and none is claimed. This is plain Git refspec
behaviour surfacing through an error message that misdescribes its own cause —
the same shape as #117, which was likewise recorded as ungrounded rather than
having a finding stretched to cover it.

This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson