Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation

["Julia Evans" <julia@jvns.ca>]

On Thu, Oct 15, 2026, at 6:39 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>     non-changes: Left these phrases alone because I don't think the proposed
>>     changes would make it more clear.
>
> Those who contributed their time to review this document did so
> believing they were suggesting improvements.  Simply dismissing
> their feedback as "style" in 'v2' without explaining what you
> disliked about their suggestions is unhelpful.  It is hard to know
> what to make of a dismissal that lacks any supporting reasoning,
> other than "I don't think".

My job to is write clear technical explanations and a big part of what I do
is to try to reconcile the point of view of experts (who understand how the
software works) and users (who know which parts are confusing).
I think we've talked about this "curse of knowledge" issue before.

I'm always happy to have a detailed discussion when it comes to accuracy,
and I'm extremely grateful for the time everyone puts in when it comes
to pointing out accuracy issues, and when figuring out when it's appropriate
to occasionally tell a "white lie" :)

The reason I was a little brief is that these in depth discussions about how
to explain a concept as clearly as possible to users are not effective if
there are no users involved in the process. It takes a lot of time without
making substantial improvements.

There are some more ideas on this site about having a "user-centric"
mindset, like using learner personas. Happy to talk about that if you think
it would be helpful. Sometimes tone can get lost here so let me know if it
would be helpful to have a video call!
https://www.writethedocs.org/blog/newsletter-june-2025/#help-contributors-think-like-users

>> diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc
>> new file mode 100644
>> index 0000000000..d8e59e10c6
>> --- /dev/null
>> +++ b/Documentation/detached-head.adoc
>> @@ -0,0 +1,57 @@
>> +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be:
>> +
>> +1. A branch, which is your current branch.
>> +2. A commit ID, when you don't have a current branch.
>> +   This is called "detached HEAD state".
>
> Differences between v1 and v3 did not make much improvement in this
> area, though.  The phrase "branch or commit" highlights the
> distinction, but it fails to clarify what is common to both, which
> is equally important.
>
> Perhaps restarting from something along this line
>
>     HEAD records the state from which your current changes started.
>     This can be a branch (the "current branch"), or it be a commit,
>     (in which case HEAD is "detached").
>
> and polishing further may take us to a better end state.  An
> important distinction that is not captured in the above (or your
> version) that we may want to cover is that when you are on a branch,
> your changes will grow that branch, and when you are not on a
> branch, your changes will not affect any branch and stay temporary.

This is a case where if we really want to make sure it's clear, we need
to go get feedback from users. There's likely a better way to explain it
but I don't think that this conversation will result in an improvement.
Really doing a good job of explaining HEAD is a pretty big project.

It's not clear to me if you think the current wording is unusable
or if you just think it could be better.

>> +It can sometimes be useful for `HEAD` to be a commit ID.
>> +For example, it lets you easily look at an old version of your code
>> +(with `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`).
>
> We should use a verb stronger than "look at" to emphasize the
> primary advantage of having the entire state visible in the working
> tree.  If a user merely wants to read or inspect a single historical
> file, they can do so easily without moving their HEAD by running
> 'git show COMMIT_ID:path/to/file'.  Checking out a commit allows
> something much more powerful.  It restores your entire working
> directory to that exact state.

Changed this to "check out an old version of your project".

>     In the detached HEAD state, you can safely build, run, and
>     experiment with any historical version of your codebase, without
>     having to worry about clobbering your branches, and you do not
>     have to clutter your repository with temporary branches.
>
> I said "safely build, run" because you had "old version of your
> CODE" in the paragraph, but if you can give examples outside the
> programming area, that would be even better.  E.g.,
>
> - Writers may able to rebuild and locally preview a complete
>   historical version of a book or documentation site to see how
>   cross-references and formatting rendered at that time.
>
> - Game Designers may open an entire historical scene in an editor
>   (like Unity or Blender) where assets, textures, and coordinates
>   must all exist in a precise, interconnected state to load
>   correctly.
>
> - Data Scientists may execute and reproduce a specific historical
>   data pipeline or model run using the exact combination of scripts
>   and datasets that existed on that day.

I like these examples, added a shorter version of a couple of
them. Also replaced "code" with "project" to make it more general.

>
>> +There are 3 main ways you can end up in detached HEAD state:
>> +
>> +1. `git checkout COMMIT_ID`, where `COMMIT_ID` is a commit ID
>> +2. `git checkout v1.3`, where v1.3 is a tag name
>> +3. `git checkout origin/main`, where `origin/main` is
>> +   a remote-tracking branch
>> +
>> +Checking out a tag puts you in detached HEAD state because `HEAD` can
>> +only be a branch or a commit, not a tag or any other reference.
>> +So `git checkout TAG` will set HEAD to the commit for that tag.
>
> A more standard phrase for "the commit for that tag" is "the tagged
> commit".

Will do.

> Because we will recommend "switch" to be a way to require to be more
> explicit when users mean to go into the detached HEAD state soon
> below, I think we would want to move the "checkout <COMMIT>" and
> "switch --detach <COMMIT>" description to here from the earlier
> "sometimes useful" paragraph, to complement the above list of ways
> to detach your HEAD.

Agreed there's some duplication here we can fix, will do.

>> +If you switch branches after making commits in detached HEAD state, Git
>> +will warn you that you might be about to "lose" those commits and print
>> +out the commit ID. You can also always find those commits later using
>> +linkgit:git-reflog[1].
>> +
>> +Here's what that warning looks like:
>> +
>> +-------------------------
>> +Warning: you are leaving 1 commit behind, not connected to
>> +any of your branches:
>> +
>> +  48c09f6 3
>> +-------------------------
>
> Your readers can guess that the 7 digit hex may probably be the
> commit object name you are about to lose, but you should use a bit
> more realistic descriptive title, not "3", to avoid confusion.  I
> know many users do not write a good log message, but even a single
> word "bugfix" is better than "3" ;-)

Oops, I meant to fix that before, thanks.