Re: [PATCH 1/5] doc: git-checkout: clarify intro

From: Julia Evans <julia@jvns.ca>
Date: Aug 26, 2025, 20:56 UTC
Message-ID: <de40e0ed-ca12-41b0-acd0-3c594078cc14@app.fastmail.com>
In-Reply-To: <xmqqqzwxkjje.fsf@gitster.g>

Thanks for the comments!

> Avoid bullet points here.  End your sentence with a full stop.

Ok, will change.

> "Restore a different
> version of files" (or "files from a different version") perhaps?
> The point being you can grab multiple with a single operation, but
> they all have to come from a single source.

I like that, will change.

>> +Here's a description of all of the modes:
>
> I am not sure if we want/need this line, though.

Will remove.

> I do not think you are dealing with a conflict here, rather
> ambiguity.  "You can use double-dash `--` to disambiguate between
> branches and paths".

Will change.

Show 9 quoted lines

>> +* `git checkout <branch> --` will force Git to treat the parameter as a
>> +  branch name or commit
>> +* `git checkout -- <pathspec>` will force Git to treat the parameter as
>> +  a set of file(s)
>
> We do not have to teach the full pathspec syntax here, but I wonder
> if we should do something to avoid leading a new reader into
> thinking they have to list files.  "...as a set of files and/or
> directories", perhaps?

I like that, will change.

>>> +1. **Switch branches**, with `git checkout <branch>`
>
> Does everybody really understand what it means to "switch branches"
> without further explanation?

My thought was that we explain what "switch branches" in immediately afterwards in more depth. ("git checkout [<branch>]: Switch to <branch>. This will update the files in the working tree...)

> Also "<branch>" -> "(<branch> | <commit>)", perhaps, as working on
> the unnamed branch (aka detached HEAD) behaves very much the same
> way as working on a named branch.

I feel mixed about this one.

One way to look at it is that `git checkout` has two modes: one where you update `HEAD` and one where you don't. I think from a "git internals" point of view this makes a lot of sense, but my impression is that most "regular" Git users think of "switching to detached HEAD state" as being a very different operation from "switching branches", not as basically equivalent except for one small detail.

Another way to look at it is that the "git checkout <branch> | <commit>"'s main role is to switch branches, and that "git checkout <commit>" is sort of an edge case and that we can leave its explanation to a few lines later on. That's the stance I've taken here, but I'm open to hearing other points of view.