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

["Rubén Justo" <rjusto@gmail.com>]

On 16-feb-2024 04:32:10, Dragan Simic wrote:
> 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>]

Well, my point was not about new terms in this series, but to see if the
idea of reusing an existing one might be of interest.

I find it interesting to have common terms like "<commit>" "<path>",
"<envvar>"...

This builds intuition in the user, making it easier to grasp the meaning
of a term, which refers to a similar /thing/, regardless of being used
in different contexts.  And in turn, it can also help to better
understand the context.

     Side note:  My gut tells me that my patch 5aea3955bc (branch:
     clarify <oldbranch> term, 2024-01-06) which was originated by a
     report [1] of a user who found the documentation confusing, would
     have been less likely to happen (the report and consequently my
     patch) if "<branchname>" had been used instead of "<oldbranch>" in
     the documentation.  Not because "<branchname>" is a better name,
     but because it is already being used in other commands with a
     clearer meaning of: "if not specified it defaults to the current
     branch".  And because of that a user might have be able to fill the
     gaps in -m|-c.  Of course this is based on my intuition, which I
     know is seriously biased.

     [1] https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/

And not only can it be of help to the user, but also to developers (or
reviewers) when documenting new commands or options;  because there is
no need to search for a, maybe new, name if there is one that is
consolidated.

Perhaps, less names can also improve the lives of translators by making
it easier to reuse some of the translations.

As I write, I realise that all this probably belongs to CodingGuideLines
or similar.  Or maybe it is too academic to be practical.  I Dunno.

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

So, to your proposal:  it does not make things worse, and it reuses
terms that are already used elsewhere:

	$ for a in '<new>' '<old>' '<name>'; do echo $a $(git grep --no-line-number -E "$a" v2.44.0-rc1 -- Documentation/git-*.txt | wc -l); done
	<new> 7
	<old> 7
	<name> 147

But based on the idea I've just described, IMHO the user might not
easily find the similarities in <old> with <name>:

>      'git branch' (-c | -C) [<old>] <new>
>      'git branch' (-d | -D) [-r] <name>...

At least, not better than with <oldbranch> and <branchname>.

And it won't be easy either with <name> and other man pages.  For
example we have:

	$ git grep -E 'git checkout.*(new-)?branch' Documentation/git-checkout.txt
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [<branch>]
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach [<branch>]
	Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
	Documentation/git-checkout.txt:'git checkout' [<branch>]::
	Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch>
	Documentation/git-checkout.txt:'git checkout' -b|-B <new-branch> [<start-point>]::
	Documentation/git-checkout.txt:$ git checkout <branch>
	Documentation/git-checkout.txt:'git checkout' --detach [<branch>]::
	Documentation/git-checkout.txt:     "git branch" with "-f" followed by "git checkout" of that branch;
	Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch>

On the names chosen, the risk of bikesheeding is high and there is
nothing wrong here, so it is way better to let you work.  You have taken
the initiative from Junios's response to my patch, so thank you for
that.

> 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, :)

Yeah, but maybe we can do it without writing it down :)

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