Why can't Git resolve remote branches when --single-branch is used?

Question

So, we frequently optimize clones by effectively cloning with --single-branch. However, we are then unable to get additional branches later. What is the difference, plumbing-wise, between a git clone with and without --single-branch? How can we fetch down additional branches later?

A standard clone:

$ git clone -b branch-name https://repo.url standard
$ cd standard
$ git checkout remote-branch
Branch 'remote-branch' set up to track remote branch 'remote-branch' from 'origin'.
Switched to a new branch 'remote-branch'

A single-branch clone:

$ git clone -b branch-name --single-branch https://repo.url singlebranch
$ cd singlebranch
$ git checkout remote-branch
error: pathspec 'remote-branch' did not match any file(s) known to git

UPDATE

Per the answer from @AndrewMarshall, below, you need to update the default fetch refspec in the config. Even though you can hack your way around the fetch to pull down the right commits, your attempted checkout will absolutely deny knowing anything about that branch if you don't fix your config first:

$ git fetch origin +refs/heads/remote-branch:refs/remotes/origin/remote-branch
From https://gerrit.magicleap.com/a/platform/mlmanifest
 * [new branch]      remote-branch -> origin/remote-branch

$ git checkout remote-branch 
error: pathspec 'remote-branch' did not match any file(s) known to git

$ git remote set-branches origin --add remote-branch
$ git checkout remote-branch 
Branch 'remote-branch' set up to track remote branch 'remote-branch' from 'origin'.
Switched to a new branch 'remote-branch'

Notice we fetch it, then reconfigure, then checkout. The fetch can happen in any order (though you have to pass parameters if not in the config) but the checkout is gated by the config.

Answer 1

--single-branch works by setting the remote’s fetch property to only be the single branch name, instead of a glob:

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

So let’s add an entry with git remote set-branches:

$ git remote set-branches origin --add other-branch
$ git config --get-all remote.origin.fetch    
+refs/heads/master:refs/remotes/origin/master
+refs/heads/other-branch:refs/remotes/origin/other-branch

$ git fetch
From origin
 * [new branch]      other-branch        -> origin/other-branch

$ git checkout other-branch
Branch 'other-branch' set up to track remote branch 'other-branch' from 'origin'.
Switched to a new branch 'other-branch'

Or, alternatively, make it a glob so all branches may be fetched (the default, non-single-branch behavior) (note that the * is quoted to avoid shell expansion; the glob is for git, not the shell):

git remote set-branches origin '*'

Answer 2

Very short summary:

• if you have used "single-branch"

• you must do these TWO things

$ git remote set-branches origin --add other-branch

$ git fetch

• you can then

$ git checkout other-branch