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

[Dragan Simic <dsimic@manjaro.org>]

Hello Ruben and Junio,

On 2024-02-15 22:52, Rubén Justo wrote:
> 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.

Thank you, and everyone else, for the reviews and suggestions.

> 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, I'd agree with Junio's reply that suggested using even
shorter terms.  Just like "<oldbranch>" and "<newbranch>" can safely
be shortened to "<old>" and "<new>", respectively, "<branchname>"
can also be shortened to "<name>".

It's all about the context, which is improved by moving the descriptions
of the arguments closer to the descriptions of the commands.

Though, I'd prefer that we keep "<oldbranch>" and "<newbranch>" (and
"<branchname>") for now, for the sake of consistency, and I'd get them
shortened in the future patches.

>> Also, improve the descriptions of these two branch operations and,
>> for completeness, describe the outcomes of forced operations.
>> 
>> Describing the arguments together with their respective operations, 
>> instead
>> of describing them separately in a rather unfortunate attempt to 
>> squeeze more
>> meaning out of fewer words, flows much better and makes the 
>> git-branch(1)
>> man page significantly more usable.
>> 
>> The subsequent improvements shall continue this approach by either 
>> dissolving
>> as many sentences from the "Description" section into the "Options" 
>> section,
>> or by having those sentences converted into some kind of more readable 
>> and
>> better flowing prose, as already discussed and outlined. [1][2]
>> 
>> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u
>> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u
>> 
>> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
>> ---
>> 
>> Notes:
>>     This patch was originally named "branch: clarify <oldbranch> and 
>> <newbranch>
>>     terms further", submitted and discussed in another thread, [3] but 
>> the nature
>>     of the patch has changed, causing the patch subject to be adjusted 
>> to match.
>> 
>>     Consequently, this is effectively version 2 of the patch, which 
>> includes
>>     detailed feedback from Kyle and Junio, who suggested moving/adding 
>> the
>>     argument descriptions to their respective commands.  This resulted 
>> in more
>>     significant changes to the contents of the git-branch(1) man page, 
>> in an
>>     attempt to make it more readable.
>> 
>>     [3] 
>> https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u
>> 
>>  Documentation/git-branch.txt | 44 
>> +++++++++++++++---------------------
>>  1 file changed, 18 insertions(+), 26 deletions(-)
>> 
>> diff --git a/Documentation/git-branch.txt 
>> b/Documentation/git-branch.txt
>> index 0b0844293235..370ea43c0380 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be 
>> changed via the global
>>  overridden by using the `--track` and `--no-track` options, and
>>  changed later using `git branch --set-upstream-to`.
>> 
>> -With a `-m` or `-M` option, <oldbranch> will be renamed to 
>> <newbranch>.
>> -If <oldbranch> had a corresponding reflog, it is renamed to match
>> -<newbranch>, and a reflog entry is created to remember the branch
>> -renaming. If <newbranch> exists, -M must be used to force the rename
>> -to happen.
>> -
>> -The `-c` and `-C` options have the exact same semantics as `-m` and
>> -`-M`, except instead of the branch being renamed, it will be copied 
>> to a
>> -new name, along with its config and reflog.
>> -
>>  With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
>>  specify more than one branch for deletion.  If the branch currently
>>  has a reflog then the reflog will also be deleted.
>> @@ -128,18 +118,28 @@ Note that 'git branch -f <branchname> 
>> [<start-point>]', even with '-f',
>>  refuses to change an existing branch `<branchname>` that is checked 
>> out
>>  in another worktree linked to the same repository.
>> 
>> --m::
>> ---move::
>> -	Move/rename a branch, together with its config and reflog.
>> +-m [<oldbranch>] <newbranch>::
>> +--move [<oldbranch>] <newbranch>::
>> +	Rename an existing branch <oldbranch>, which if not specified 
>> defaults
>> +	to the current branch, to <newbranch>.  The configuration variables
>> +	for the <oldbranch> branch and its reflog are also renamed 
>> appropriately
>> +	to be used with <newbranch>.  Renaming fails if branch <newbranch>
>> +	already exists, but you can use `-M` or `--move --force` to 
>> overwrite
>> +	the files in existing branch <newbranch> while renaming.
>> 
>> --M::
>> +-M [<oldbranch>] <newbranch>::
>>  	Shortcut for `--move --force`.
>> 
>> --c::
>> ---copy::
>> -	Copy a branch, together with its config and reflog.
>> +-c [<oldbranch>] <newbranch>::
>> +--copy [<oldbranch>] <newbranch>::
>> +	Copy an existing branch <oldbranch>, which if not specified defaults
>> +	to the current branch, to <newbranch>.  The configuration variables
>> +	for the <oldbranch> branch and its reflog are also copied 
>> appropriately
>> +	to be used with <newbranch>.  Copying fails if branch <newbranch>
>> +	already exists, but you can use `-C` or `--copy --force` to 
>> overwrite
>> +	the files in existing branch <newbranch> while copying.
>> 
>> --C::
>> +-C [<oldbranch>] <newbranch>::
>>  	Shortcut for `--copy --force`.
>> 
>>  --color[=<when>]::
>> @@ -311,14 +311,6 @@ superproject's "origin/main", but tracks the 
>> submodule's "origin/main".
>>  	given as a branch name, a commit-id, or a tag.  If this
>>  	option is omitted, the current HEAD will be used instead.
>> 
>> -<oldbranch>::
>> -	The name of an existing branch.  If this option is omitted,
>> -	the name of the current branch will be used instead.
>> -
>> -<newbranch>::
>> -	The new name for an existing branch. The same restrictions as for
>> -	<branchname> apply.
>> -
>>  --sort=<key>::
>>  	Sort based on the key given. Prefix `-` to sort in descending
>>  	order of the value. You may use the --sort=<key> option