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

[Dragan Simic <dsimic@manjaro.org>]

On 2024-02-16 00:34, Rubén Justo wrote:
> 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:
>>> 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.

Here's what I think the example from above should eventually look like:

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

Though, it's something to be left for future patches, which will move
more argument descriptions to the respective command descriptions.

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

We don't say that yet, :) because the description of the command for
editing branch descriptions is detached from the description of its
arguments.  The plan is to move all of them together.

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