Why does git checkout with explicit refs/heads/branch give detached HEAD?
You're not checking out a branch; you're merely checking out a commit that happens to be the head of a branch. Branches are one-way pointers: given a branch, you can determine the exact commit which is the head of that branch, but you cannot take an arbitrary commit and determine which branch(es) it is the head of. Thus, if you were to make a new commit, Git would not know which, if any, branch to update.
The checkout
command distinguishes between two cases (well, actually "many", but let's start with just the two :-) ):
- "I want to ‘get on a branch’; here's a branch name": e.g.,
git checkout branch
. - "I want to look at some particular revision, and get off any branch; here's a branch-identifier that is not a branch name": e.g.,
git checkout 6240c5c
.
(Personally, I think these should use different command names, but that's just me. On the other hand, it would obviate all the weirdness described below. Edit, Jun 2020: In Git 2.23 or later, these are in a separate command now: git switch
is the branch-changer, and it requires --detach
to go to a detached HEAD; git restore
implements the file-restorer mentioned later in this posting. You can still use the existing git checkout
command the same way as in pre-2.23 Git, though.)
Now, let's say that you want the former. That's easiest to write by just writing out the branch name, without the refs/heads/
part.
If you want the latter, you can specify a revision by any of the methods listed in gitrevisions, except for any method that results in "getting on the branch".
For whatever reason, the algorithm chosen here—it is documented in the manual page, under <branch>
—is this: If you've written a name that, when adding refs/heads/
to it, names a branch, git checkout
will put you "on that branch". If you specify @{-N}
or -
, it will look up the N-th older branch in the HEAD
reflog (with -
meaning @{-1}
). Otherwise it chooses the second method, giving you the "detached HEAD". This is true even if the name is the one suggested in gitrevisions for avoiding ambiguity, i.e., heads/xyz
when there's another xyz
. (But: you can add --detach
to avoid the "get on a branch" case even if it would otherwise get on the branch.)
This also contradicts the resolving rules listed in the gitrevisions document. To demonstrate this (although it's hard to see), I made a tag and branch with the same name, derp2
:
$ git checkout derp2
warning: refname 'derp2' is ambiguous.
Previous HEAD position was ...
Switched to branch 'derp2'
This put me on the branch, rather than detaching and going to the tagged revision.
$ git show derp2
warning: refname 'derp2' is ambiguous.
...
This showed me the tagged version, the way gitrevisions says it should.
One side note: "getting on a branch" really means "putting a symbolic reference to a branch name into the file named HEAD
in the git directory". The symbolic reference is the literal text ref:
(with trailing space) followed by the full branch name, e.g., refs/heads/derp2
. It seems kind of inconsistent that git checkout
demands the name without the refs/heads/
part in order to add the ref: refs/heads/
part, but that's git for you. :-) There may be some historic reason for this: originally, to be a symbolic reference, the HEAD
file was actually a symbolic link to the branch file, which was always a file. These days, in part because of Windows and in part just through code evolution, it has that literal ref:
string, and references may become "packed" and hence not available as a separate file anyway.
Contrariwise, a "detached HEAD" really means "putting a raw SHA-1 into the HEAD
file". Other than having a numeric value in this file, git continues to behave the same way as when "on a branch": adding a new commit still works, with the new commit's parent being the current commit. Merges can still be done as well, with the merge commit's parents being the current and to-be-merged commits. The HEAD
file is updated with each new commit as it happens.1 At any point you can create a new branch or tag label pointing to the current commit, to cause the new chain of commits to be preserved against future garbage collection even after you switch off the "detached HEAD"; or you can simply switch away and let the new commits, if any, get taken out with the usual garbage-collection. (Note that the HEAD
reflog will prevent this for some time, default 30 days I think.)
[1 If you're "on a branch", the same auto-update happens, it just happens to the branch that HEAD
refers to. That is, if you're on branch B
and you add a new commit, HEAD
still says ref: refs/heads/B
, but now the commit-ID that you get with git rev-parse B
is the new commit you just added. This is how branches "grow": new commits added while "on the branch" cause the branch reference to move forward automatically. Likewise, when in this "detached HEAD" state, new commits added cause HEAD
to move forward automatically.]
For completeness, here's a list of other things git checkout
can do, that I might have put in various separate commands if I had such powers:
- check out a specific version of some path(s), writing through the index:
git checkout revspec -- path ...
- create a new branch:
git checkout -b newbranch
(plus options forgit branch
) - create a new branch that, if and when you do a commit on it, will be a root commit:
git checkout --orphan
(this puts you "on a branch" that does not yet exist, i.e., writesref: refs/heads/branch-name
intoHEAD
but does not create the branchbranch-name
; this is also howmaster
is an unborn branch in a new repository) - create or re-create a merge or merge conflict:
git checkout -m ...
- resolve a merge conflict by picking one or the other "side" of the merge:
git checkout --ours
,git checkout --theirs
- interactively select patches between repository objects and work-tree files, similar to
git add --patch
:git checkout --patch