Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation
Show 24 quoted lines
> Here's what Junio suggested^, and here's what v4 has
>
> +`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".
> +
> +It can sometimes be useful for `HEAD` to be a commit ID, because
> +it lets you easily check out an old version of your project. For
> +example, a data scientist could use this to run an old version of a
> +data pipeline or a programmer could use this to figure out when a bug
> +was introduced.
>
> I do not personally think it's worth focusing on "the state from which
> your current changes started" (even leaving aside the "what if I have
> no changes?" moment), in part because I don't think that's how most
> users conceive of HEAD. Other than that detail, I think the first
> paragraphs of each option coincide.
>
> There are some quotes which use the "it's the parent of the next
> commit" mental model, though, so we could include a comment on that?
> It might be distracting, and could make its way into some kind of
> admonition/aside if need be?
Yeah I agree the "it's the parent of the next commit" would be distracting unless there's a specific reason we need to include it.
I agree "the state from which your current changes started" isn't right but I think if we reinterpret it as "the current commit you have checked out" (which I think has the same or a very similar meaning) then it'll seem familiar to folks and might even help.
Show 11 quoted lines
> The second paragraphs differ a bit, with Junio's containing some bits
> about clobbering extant branches and not needing temporary branches. I
> think we could work something in there, like
>
> It can sometimes be useful for `HEAD` to be a commit ID,
> because it lets you easily check out an old version of your
> project. For example, a data scientist could use this to run
> an old version of a data pipeline or a programmer could use
> this to figure out when a bug was introduced. By detaching
> `HEAD`, you don't need to worry about clobbering an existing
> branch or creating a temporary branch.
Thanks, I took this language. I left out "clobbering an existing branch" because I couldn't think of a reason why someone would clobber an existing branch to check out an old version of their code.
- Julia