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.
>> +* `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.
