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

[Junio C Hamano <gitster@pobox.com>]

"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".

> 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 <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.

> +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" ;-)