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

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

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.

> 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