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

> On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic <dsimic@manjaro.org> 
> wrote:
>> 
>> Move the descriptions of the <oldbranch> and <newbranch> arguments to 
>> the
>> descriptions of the branch rename and copy operations, where they 
>> naturally
>> belong.  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(-)
> 
> Thanks! I think this is a great improvement to this document.

>> 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
> 
> Very minor nit: the prevailing style in this document appears to be to
> have a single space after the period, but it's definitely
> inconsistent. I don't see anything in Documentation/CodingGuidelines
> suggesting one way or the other, so don't consider this comment as
> blocking, just informational. If we want to achieve (eventual)
> consistency, we may want to use a single space after the period now.

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