From: Junio C Hamano Date: Thu, 15 Oct 2026 22:39:24 GMT Subject: Re: [PATCH v3] doc: checkout: rewrite detached HEAD state explanation Message-ID: In-Reply-To: "Julia Evans via GitGitGadget" 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". > 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. > +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. 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. > +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". 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 " and "switch --detach " description to here from the earlier "sometimes useful" paragraph, to complement the above list of ways to detach your HEAD. > +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" ;-)