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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 15, 2024, 22:13 UTC
Message-ID: <xmqq8r3lnzp0.fsf@gitster.g>
In-Reply-To: <e8fdd057-2670-4c93-b362-202a339d5f49@gmail.com>

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

Show 16 quoted lines

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