From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 15 Feb 2024 22:13:31 GMT
Subject: Re: [PATCH] branch: rework the descriptions of rename and copy operations
Message-ID: <xmqq8r3lnzp0.fsf@gitster.g>
In-Reply-To: <e8fdd057-2670-4c93-b362-202a339d5f49@gmail.com>

Rubén Justo <rjusto@gmail.com> writes:

> On 15-feb-2024 19:42:32, Dragan Simic wrote:
>
>> Move the descriptions of the <oldbranch> and <newbranch> arguments to the
>> descriptions of the branch rename and copy operations, where they naturally
>> belong.
>
> Thank you Dragan for working on this.
>
> Let me chime in just to say that maybe another terms could be considered
> here;  like: "<branchname>" and "<newbranchname>" (maybe too long...) or
> so.
>
> I have no problem with the current terms, but "<branchname>" can be a
> sensible choice here as it is already being used for other commands
> where, and this may help overall, the consideration: "if ommited, the
> current branch is considered" also applies.

Actually, we should go in the opposite direction.  When the use of
names are localized in a narrower context, they can be shortened
without losing clarity.  For example:

    -m [<old>] <new>::
	rename the <old> branch (defaults to the current one) to
	<new>.

is just as clear as the same description with <oldbranch> and
<newbranch>.  With the original text without any of the suggested
changes, <oldbranch> and <newbranch> appeared very far from the
context they are used in (i.e. the description for -m and -c), and
it may have helped readers to tell that these are names of branches.
But if the context is clear that we are talking about "renaming"
branches, there is not as much added benefit to say "branch" in
these names as in the current text.