Subject: Re: [PATCH v4 1/5] doc: git-rebase: start with an example

From: Junio C Hamano <[email-masked]>
Date: Tue, 12 Aug 2025 11:07:21 -0700

"D. Ben Knoble" <[email-masked]> writes:

>> > Junio has already expressed a preference for "checkout" here c.f.
>> > <[email-masked]>. I think that is technically correct as
>> > "topic" can be a commitish and "git switch <object-id>" fails without
>> > "--detach".

I wanted the new documentation text to use what was already used in
the parts of the document that are not touched; otherwise we end up
with text that uses checkout in some places and switch in others,
which would invite confusions among uninitiated readers, who
rightfully would wonder what criteria were used to decide which one
among these two different commands to use.  And teaching that these
two commands are quasi-equivalent with possibly subtle differences
is not what the documentation of "git rebase" needs to do---it is a
distraction.

I do not mind a new proposal to do a documentation sweep, aiming for
Git 3.0 timeframe, to examine all mentions of "git checkout" in the
documentation and replace them with "git switch" or "git restore"
when appropriate (there are of course ones that are not for obvious
reasons, like the ones in "git checkout" documentation itself, and
possibly in "git switch" and "git restore" documentation pages that
may say things like "'git switch X' is similar to 'git checkout Y'").

But let's leave that outside this topic.

Thanks.