Subject: Re: [PATCH v2 3/5] doc: git-checkout: don't use "reset"

From: "Julia Evans" <[email-masked]>
Date: Mon, 01 Sep 2025 10:28:44 -0400

> I think the source of the problem is not that they "don't know what
> the term means" at all.  Isn't the real problem that the use of the
> verb in the original sentence you are correcting in this patch is
> vague and does not say what the branch is reset *to*?

I agree this is a reasonable approach here, will try that.

>> Many Git users don't know what the term "reset" means. Resolve this by:
>
> Even though it is the name of one of the most often used commands?
> And yet a separate step in this series made the claim that everybody
> knows what "switch" means because it is the name of another command?

I'm surprised to hear you say that "reset" is one of the most often
used Git commands -- what I frequently hear from Git users is that they
use `git reset` only in "emergencies" where something has gone wrong
and that they're afraid of using it.

I'm curious about whether there are any datasets about which Git
commands are the most frequently used, or if it would be worth me
trying to build one.

>> ... This is the
>> +transactional equivalent of
>>  +
>>  ------------
>>  $ git branch -f <branch> [<start-point>]
>>  $ git checkout <branch>
>>  ------------
>>  +
>> -that is to say, the branch is not reset/created unless "git checkout" is
>> -successful (e.g., when the branch is in use in another worktree, not
>> -just the current branch stays the same, but the branch is not reset to
>> -the start-point, either).
>> +that is, the branch will not be created or modified unless
>> +`git checkout` is successful.
>>  
>>  `git checkout --detach [<branch>]`::
>>  `git checkout [--detach] <commit>`::
>
> This is in response to "transactional equivalent".  I've always felt
> that there is no need to say "transactional" in this at all.  IOW, I
> wouldn't have minded if we rewrote this more heavily.

"Transactional equivalent" was bothering me too and I like the
idea of rewriting it, will give it a shot.