Why does git checkout with explicit refs/heads/branch give detached HEAD?

git, git-checkout

Solution

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 for `git 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., writes `ref: refs/heads/branch-name` into `HEAD` but does not create the branch `branch-name`; this is also how `master` 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`

Problem

Original source