From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 5/5] doc: git-checkout: clarify restoring files section
Date: Thu, 28 Aug 2025 09:26:54 -0400 [thread overview]
Message-ID: <80fba886-4693-4f31-b64f-438391edc3da@app.fastmail.com> (raw)
In-Reply-To: <xmqqiki9hfg2.fsf@gitster.g>
On Tue, Aug 26, 2025, at 6:43 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail•com> writes:
>
>> 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).
>
>> +
>> -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 ;-).
Thanks, this section of the man page is not easy and this is very
useful feedback. Will work on improving all of these points.
next prev parent reply other threads:[~2025-08-28 13:27 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-25 19:08 [PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-26 18:46 ` Junio C Hamano
2025-08-26 18:51 ` Junio C Hamano
2025-08-26 20:56 ` Julia Evans
2025-08-28 14:00 ` D. Ben Knoble
2025-08-28 22:34 ` Julia Evans
2025-08-28 23:44 ` Junio C Hamano
2025-08-29 13:39 ` D. Ben Knoble
2025-08-29 21:00 ` Junio C Hamano
2025-09-03 23:48 ` D. Ben Knoble
2025-08-25 19:08 ` [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-26 21:38 ` Junio C Hamano
2025-08-28 12:11 ` Julia Evans
2025-08-28 15:45 ` Junio C Hamano
2025-08-28 18:24 ` Julia Evans
2025-08-25 19:08 ` [PATCH 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-08-26 22:43 ` Junio C Hamano
2025-08-28 13:26 ` Julia Evans [this message]
2025-08-28 19:08 ` D. Ben Knoble
2025-08-28 19:59 ` Julia Evans
2025-08-28 20:38 ` Junio C Hamano
2025-08-29 13:48 ` D. Ben Knoble
2025-08-29 11:45 ` [PATCH v2 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-29 15:58 ` Junio C Hamano
2025-09-02 17:14 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-29 16:03 ` Junio C Hamano
2025-09-02 17:16 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-29 16:22 ` Junio C Hamano
2025-09-01 14:28 ` Julia Evans
2025-09-02 16:10 ` Junio C Hamano
2025-08-29 11:45 ` [PATCH v2 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 1/6] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 4/6] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 5/6] doc: git-checkout: split up restoring files section Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 6/6] doc: git-checkout: clarify " Julia Evans via GitGitGadget
2025-09-03 21:29 ` Junio C Hamano
2025-09-03 21:09 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Junio C Hamano
2025-09-03 21:28 ` Julia Evans
2025-09-10 19:14 ` [PATCH v4 0/7] " Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 1/7] doc: git-checkout: clarify intro sentence Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-29 18:07 ` Kristoffer Haugsbakk
2025-10-02 18:37 ` [PATCH] doc: git-checkout: fix placeholder markup kristofferhaugsbakk
2025-10-16 22:11 ` [PATCH resend] " kristofferhaugsbakk
2025-10-17 13:56 ` Julia Evans
2025-10-17 15:50 ` [PATCH v2] " kristofferhaugsbakk
2025-09-10 19:14 ` [PATCH v4 5/7] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 6/7] doc: git-checkout: split up restoring files section Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 7/7] doc: git-checkout: clarify " Julia Evans via GitGitGadget
2025-09-11 13:01 ` [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section Ben Knoble
2025-09-12 14:05 ` Julia Evans
2025-09-12 14:26 ` Kristoffer Haugsbakk
2025-09-15 23:22 ` Junio C Hamano
2025-09-16 6:41 ` Kristoffer Haugsbakk
2025-09-12 16:23 ` Junio C Hamano
2025-09-17 18:38 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=80fba886-4693-4f31-b64f-438391edc3da@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox