On 15-feb-2024 14:13:31, Junio C Hamano wrote:
> Rubén Justo <rjusto@xxxxxxxxx> 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.
