Re: [PATCH] branch: rework the descriptions of rename and copy operations

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 20, 2024, 18:24 UTC
Message-ID: <xmqqttm3ouxy.fsf@gitster.g>
In-Reply-To: <35738a93f5cbace5b3235ce614b7afbf@manjaro.org>

Dragan Simic <dsimic@manjaro.org> writes:

Show 5 quoted lines

>> My advice would be to stick to <old> vs <new> that contrasts well.
>
> I appreciate the directness and honesty.  How about using "<oldbranch>"
> and "<newbranch>" instead, which, although more wordy, would be more
> consistent with "<branch>" that's used in a number of other places?

I have slight aversion to non-words like "oldbranch" (not "old-branch"), but not that much.

Quite honestly, in a document whose primary topic is "branch", I doubt that repeating "branch" all over the place would be the consistency we should be aiming for in the first place, when it is clear from the context that we are talking about branches.

The updates we are making to Documentation/git-branch.txt that (1) slims wordy description of different modes in the DESCRIPTION section, (2) make option description of "-m" mention what argument(s) the option takes, and (3) rmove standalone <newbranch> and <oldbranch> description are all about making the necessary piece of information easier to find in one place (namely, the option description where "-m [<one branch name>] [<the other branch name>]" is described) without having to jump around all over in the documentation, so in that sense, I would think the way to go is to aim for brevity that takes advantage of the local context.