On Mon, Aug 25, 2025 at 3:31 PM Julia Evans via GitGitGadget <gitgitgadget@xxxxxxxxx> wrote: > > From: Julia Evans <julia@xxxxxxx> > > - Use the term "Restore" to mirror `git restore` > - Many Git users do not know what a "tree-ish" is. Clarify by using an > example of each case, and by saying "commit or tree" in the text > instead of "<tree-ish>" Wishful thinking (see glossary comments): I wish we could teach them about "tree-ish"s here rather than stop using useful shorthands altogether. Of course, then we have to wonder where we can use the shorthand and where we must do the "spell it out (give an abbreviation)" dance. Hm. > diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc > index b343d292b30b..9f2b86ac5368 100644 > --- a/Documentation/git-checkout.adoc > +++ b/Documentation/git-checkout.adoc > @@ -82,20 +82,21 @@ Omitting _<branch>_ detaches `HEAD` at the tip of the current branch. > -The index may contain unmerged entries because of a previous failed merge. > -By default, if you try to check out such an entry from the index, the > -checkout operation will fail and nothing will be checked out. > -Using `-f` will ignore these unmerged entries. The contents from a > +If you specify a commit or tree to restore from (for example `git > +checkout main file.txt`), this will restore the version of the file(s) > +from that commit or tree. This overwrites the file in the working > +directory and stages the file's contents. > ++ > +If you do not specify where to restore from (for example `git checkout > +file.txt`), this will replace the file(s) with the version from the index. > +If you check out a file with an unresolved merge Possibly a missing paragraph break here? > +conflict, the checkout operation will fail and no changes will be made. > +Using `-f` will ignore the merge conflict. The contents from a > specific side of the merge can be checked out of the index by > using `--ours` or `--theirs`. With `-m`, changes made to the working tree > file can be discarded to re-create the original conflicted merge result. > - > `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`:: I think I would expect to keep this break, but I might be misreading something. -- D. Ben Knoble
