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

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