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

From: Dragan Simic <dsimic@manjaro.org>
Date: Feb 18, 2024, 20:38 UTC
Message-ID: <be91f3ad9305366c1385c2da4881537e@manjaro.org>
In-Reply-To: <c00f6efe-d1f4-4f2c-99cc-ac7a6d93c9ff@gmail.com>

Hello Ruben,

On 2024-02-17 15:58, Rubén Justo wrote:

Show 11 quoted lines

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

Good point, ensuring such consistency would be really good.

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

... or "<branch>". :)

Show 5 quoted lines

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

Agreed, consistency is good.

Show 15 quoted lines

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

After thinking a bit more about the whole thing, I think that using "<branch>" instead of "<name>" or "<branchname>" would be our best choice. It would be simple, direct and clear.

Regarding the branch copy and rename operations and their argument names, perhaps the following would be a good choice:

     --copy [<branch>] <destination>
     --move [<branch>] <destination>

It would clearly reflect the nature of the performed operations, while still using "<branch>" consistently, this time to refer to the source branch. Using "<destination>" to select the destination name should be pretty much self-descriptive, if you agree.

Of course, I'll get back to this later in this message.

Show 7 quoted lines

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

Perhaps. That should be another example of the long-term benefits achieved through improved consistency.

Show 17 quoted lines

>>      '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>:

I agree after thinking about the whole thing a bit more.

Show 22 quoted lines

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

I'd say this solidifies "<branch>" as, hopefully, our best choice, as already proposed above.

Show 5 quoted lines

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

I hope we'll eventually produce a great git-branch(1) man page together. After that's completed, I have some more plans for improving git-branch, by introducing some additional operations.

Show 7 quoted lines

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

Maybe, :) but again, spending a few additional words to describe that might actually be beneficial. We'll see how it goes.