There is no origin/PATCH_branch
. Instead, there is a tag that is very poorly named, and in your clone, you have checked out that tag, resulting in the detached HEAD.
Why this happened
If you consult the gitrevisions
documentation, you will see a sequenced list of possibilities for resolving a symbolic reference name:
<refname>, e.g. master, heads/master, refs/heads/master
A symbolic ref name. E.g. master typically means the commit object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say heads/master to tell Git which one you mean. When ambiguous, a <refname> is disambiguated by taking the first match in the following rules:
If $GIT_DIR/<refname> exists, that is what you mean (this is usually useful only for HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and CHERRY_PICK_HEAD);
otherwise, refs/<refname> if it exists;
otherwise, refs/tags/<refname> if it exists;
In this particular case, the name PATCH_branch
is not in fact ambiguous, but the rules (especially the parts I put in bold text) still apply: if there is a tag named PATCH_branch
, and neither rule #1 nor rule #2 are able to resolve the name to a commit hash but the tag can, Git can check out the tag, so we don't need to go on to look at rules 4, 5, and 6; but here they are anyway:
otherwise, refs/heads/<refname> if it exists;
otherwise, refs/remotes/<refname> if it exists;
otherwise, refs/remotes/<refname>/HEAD if it exists.
Of these six rules, only one—specifically rule 4—will not give you a "detached HEAD" checkout. Since you did get a detached HEAD, clearly rule 4 did not apply.
Special rules for git checkout
Now, git checkout
has its own additional "rule 4.5", where it will create refs/heads/refname
in some situations. That extra git checkout
rule is the rule you were expecting to experience here, I believe.
Specifically, git checkout
will, even before trying rules 1, 2, and 3, try rule 4. If this fails, git checkout
will then see if it can create a local branch based on the existence of exactly one matching remote-tracking branch. In either of these two cases, rule 4 then applies and git checkout
does not give you a "detached HEAD". Otherwise git checkout
goes back and starts over at rule 1.
Clones initially have only remote-tracking branches and tags
You mentioned that this is a new clone, and in new clones, there is one (and only one) remote and by default, you get all of its branches as remote-tracking branches. If the remote is named origin
(as it usually is), these remote-tracking branches live in the refs/remotes/origin/
part of your repository's name-space. You also, by default, get all of the remote's tags, which live in your refs/tags/
name-space.
The last step of git clone
is git checkout
When you run:
$ git clone <url>
or:
$ git clone <url> <destination>
Git will connect to the given URL, verify that there is a Git repository there, ask that remote for a list of all branches and tags, and then create a clone repository for you in the given destination directory (or use the last part of the URL to make a default destination name). In that repository, Git will add a remote named origin
(or whatever name you specify with -o
). It will copy all of their tags to your tags, and copy their branches to your refs/remotes/origin/
remote-tracking branches (if you specify a different -o
, modify these names as appropriate). The resulting repository has no local branches at all.
However, at this point, git clone
invokes git checkout
, to check out some branch—the one you told it to (git clone -b
) or, by default, the one your Git got from the remote, usually master
. Of course, you don't have a local master
branch, and this is where what I called "rule 4.5" comes in: git checkout
looks to see if there is an origin/master
, and of course there is, so your Git makes a new local branch named master
that tracks remote-tracking branch origin/master
.1 This is, in fact, how you get your master
branch!
When you ran git checkout PATCH_branch
you no doubt expected Git to follow this same pattern: there should be an origin/PATCH_branch
, and your Git should create a new (regular, ordinary, local) branch named PATCH_branch
based on origin/PATCH_branch
(which is really refs/remotes/origin/PATCH_branch
).
But instead, what you have is a tag, refs/tags/PATCH_branch
. So the special "create local branch from remote-tracking branch" rule does not apply, and the "early application of rule 4" does not apply either, and we're left with rules 1 and 2 (which do not apply) and then rule 3, and that got you the "detached HEAD" checkout.
You can create a local branch, but be careful!
Look back over the six rules. Suppose you have both refs/heads/PATCH_branch
and refs/tags/PATCH_branch
. Note that rule 3 normally applies before rule 4: most Git commands will treat PATCH_branch
as the tag.
Because git checkout
is special, and applies rule 4 first (instead of after rule 3), you will be able to check out the local branch. But other Git commands will behave in ways you won't expect, as they will apply rule 3 first.
The tag is poorly named
Tag names should probably not contain the word "branch". Whether you can or should fix this is an administrative question more than a technical one. Find out who created the tag and why, and see if you can get everyone on your project to agree that this is a bad name and thus to delete it.
1The names here are admittedly terribly confusing. The local branch master
is not a "(remote-)tracking branch", but it is "tracking" another branch. The remote-tracking branch origin/master
is something your Git stores locally; it's just automatically updated from whatever your Git sees on origin
, whenever your Git talks with their Git. So your branch—your master
—is "tracking" a remote-tracking branch, origin/master
. All that really means is that your master
has origin/master
set as its upstream, which is a newer, somewhat better term. Older Git documentation (pre-version-1.8 or so) does not define upstream quite this carefully, though.