From: Rubén Justo <rjusto@gmail.com>
Date: Thu, 15 Feb 2024 23:34:28 GMT
Subject: Re: [PATCH] branch: rework the descriptions of rename and copy operations
Message-ID: <2a4de8c4-4955-4891-859c-58730a41e5af@gmail.com>
In-Reply-To: <xmqq8r3lnzp0.fsf@gitster.g>

On 15-feb-2024 14:13:31, Junio C Hamano wrote:
> 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.

I did not mean to have longer terms, sorry for that.

I was thinking more in the synopsis:

    'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
    'git branch' --unset-upstream [<branchname>]
    'git branch' (-m | -M) [<branchname>] <new>
    'git branch' (-c | -C) [<branchname>] <new>
    'git branch' (-d | -D) [-r] <branchname>...
    'git branch' --edit-description [<branchname>]

To have more uniformity in the terms, which can be beneficial to the
user.

We don't say that "--edit-description" defaults to the current branch;
It is assumed.  Perhaps we can take advantage of that assumption in
-m|-c too.

Of course, there is no need (perhaps counterproductive) to say "branch"
if the context makes it clear it is referring to a branch.

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