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

From: Julia Evans <julia@jvns.ca>
Date: Sep 1, 2025, 14:28 UTC
Message-ID: <9d708558-df36-4bdd-a914-522228b27215@app.fastmail.com>
In-Reply-To: <xmqqh5xqnlmo.fsf@gitster.g>

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

Show 5 quoted lines

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

Show 21 quoted lines

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