On Fri, Aug 29, 2025 at 5:00 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > "D. Ben Knoble" <ben.knoble@xxxxxxxxx> 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. I'd say your first version matches my concept of that mode, but it's heavy on the operation (do this, do that) vs the declaration (desired end state). Of course the second version still has the verb "update," but we emphasize less "how" to update and more the results of said update? > Anyway, thanks for a review. :) -- D. Ben Knoble
