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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 26, 2025, 22:43 UTC
Message-ID: <xmqqiki9hfg2.fsf@gitster.g>
In-Reply-To: <b641874627b3898831c3965616e936bd4ee310df.1756148933.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 14 quoted lines

> 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.
>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
>  `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
>  
> -	Overwrite the contents of the files that match the pathspec.
> -	When the _<tree-ish>_ (most often a commit) is not given,
> -	overwrite working tree with the contents in the index.
> -	When the _<tree-ish>_ is given, overwrite both the index and
> -	the working tree with the contents at the _<tree-ish>_.
> +	Restore another version of the file(s) that match the pathspec.

The same comment about "files and directories from a different version" applies here.

Also, I am not so sure about the claim that the verb "restore" is better understood than "overwrite" due to the presence of "git restore". If you are working on, say, an older maintenance track, and want to borrow what is in a few files from the development branch, you may say "git restore --source=develop files..." go grab them down to your current working tree. But at least to me, "restore" has a connotation to get back what you used to have, but the contents in these files you are grabbing had not existed on the older maintenance track you are working on, ever, and "restore" had always made me go "Huh?".

I am not suggesting to change the command name "restore"; I am suggesting the operation that command does using a verb that is different from "restore" (in an ancient thread, we tried to explain "checkout" without using "checkout" as the primary verb to describe what it does, it is the same thing).

Show 5 quoted lines

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

OK. I suspect the most common is to "restore" from HEAD, and the "Huh?"ness of using the verb "restore" goes away. It clearly is getting you back to where you were back when your working tree was in sync with HEAD. Perhaps use "git checkout HEAD file.txt" for the example?

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

That is a very negative way to state it. It is not "do not specify where". If you do not give tree, you are actively specifying that you want things 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.

This is confusing in a way different from the original. During a conflicted merge, you will see a few stages until they are resolved.

 (1) The working tree file has conflict markers and text from
     multiple variants.  The index has higher-stage cache entry for
     such a path.

 (2) The user edits the working tree file to resolve the conflicts.
     Once all the conflict markers are removed, some people may say
     "the merge conflict has been resolved".  To Git, the path is
     still unmerged.

 (3) The user tells the index what the resolution is, with commands
     like "git add", "git rm", and the like.  The higher-stage cache
     entries in the index for the path are moved and replaced with a
     single stage-0 entry.  To Git, the path is now merged.

So, "a file with an unresolved merge conflict" would not mean what you wanted to say for those who consider that dealing with the working tree files is enough to declare victory and consider the conflict has been resolved.

> +Using `-f` will ignore the merge conflict.  The contents from a

This changes the meaning to most people from what the original meant. If you have a file F with merge conflicts in the earlier part but the later part merged cleanly, does "git checkout -f F" ignore the conflicted part and overwrite the rest of the file somehow?

If you wanted to avoid the term "unmerged cache entries", you can say "unmerged paths".

Taking all of the above into consideration, perhaps...

    When you are in the middle of a conflicted merge (or
    cherry-pick, "stash pop", etc.) and haven't told Git what the
    resolution for these conflicted paths are with "git add" and
    friends, using "git checkout" to check out such an unmerged path
    out of the index would fail and the command exits with non-zero
    exit status.

    When the `-f` option is given, these unmerged paths are left
    untouched, instead of triggering an error.  For all other
    (i.e. merged) paths that match the <pathspec>, the working tree
    files are overwritten by the version recorded in the index.

or something along that line, but with a readability enhancement like you have been doing in your series ;-).