From: Dragan Simic <dsimic@manjaro.org>
Date: Tue, 20 Feb 2024 19:32:23 GMT
Subject: Re: [PATCH] branch: rework the descriptions of rename and copy operations
Message-ID: <95b86d73f934b486171c7e169080f43e@manjaro.org>
In-Reply-To: <xmqqttm3ouxy.fsf@gitster.g>

On 2024-02-20 19:24, Junio C Hamano wrote:
> Dragan Simic <dsimic@manjaro.org> writes:
> 
>>> 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.

It's hard not to agree with the way you laid this out. :)

In a nutshell, the way I see it, using "<old>" and "<new>" is also fine.
It's also fine with me to use "<name>" instead of "<branch>";  in fact,
if we go with "<old>" and "<new>", we should go with "<name>", too.