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

[Kyle Lippincott <spectral@google.com>]

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
>