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

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

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

>> +1. **Switch branches**, with `git checkout <branch>`
>> +2. **Restore a different version of a file**, for example with `git
>> +   checkout <commit> <filename>` or `git checkout <filename>`
>> +
>> +See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
>> +Here's a description of all of the modes:
>
> This looks good—I initially scratched my head thinking there were 3
> modes, but unifying "update files to match index" and "update files to
> match specified tree" is easier to digest in this presentation.

Yup.  And on the other side, unifying "prepare to extend the history
of a branch" and "prepare to create a new history starting at a
commit" (aka detached HEAD) into one is equally good.

But I am wondering what is the most common perception of the second
mode.  I've always thought that the action was to "grab things out
of the index or out of a tree-ish and overwrite the working tree
files", and it takes me an extra effort to read, think, understand
and finally realize that "update working tree files to match either
the index or a tree-ish" is equivalent to it.

Anyway, thanks for a review.