Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section

>
> From: Julia Evans <julia@jvns.ca>
>
> - 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>"

> 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

> +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>...]`::