Re: [PATCH] branch: clarify <oldbranch> and <newbranch> terms further

From: Kyle Lippincott <spectral@google.com>
Date: Feb 5, 2024, 23:53 UTC
Message-ID: <CAO_smViHVZRObZjg0tEPXezJZb7wvs9LQdHUFJQTK4-ASCfrmw@mail.gmail.com>
In-Reply-To: <e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org>

On Mon, Feb 5, 2024 at 4:45 AM Dragan Simic <dsimic@manjaro.org> wrote:

Show 31 quoted lines

>
> Clarify further the uses for <oldbranch> and describe the additional use
> for <newbranch>.  Mentioning both renaming and copying in these places might
> seem a bit redundant, but it should actually make understanding these terms
> easier to the readers of the git-branch(1) man page.
>
> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
> ---
>  Documentation/git-branch.txt | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 0b0844293235..7392c2f0797d 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -312,12 +312,14 @@ superproject's "origin/main", but tracks the submodule's "origin/main".
>         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.
> +       The name of an existing branch to be renamed or copied.
> +       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.
> +       The new name for an existing branch, when renaming a branch,
> +       or the name for a new branch, when copying a branch.  The same
> +       naming restrictions apply as for <branchname>.

The precision here makes me worry that I'm potentially missing something when reading this, and has made me re-read it multiple times to try to figure out what it is.

I think this would be cleaner:

The name to give the branch created by the rename or copy operation. The operation fails if <newbranch> already exists, use --force to ignore this error. The same naming restrictions apply as for <branchname>.

I'm not super pleased with that second sentence, and maybe we shouldn't include it here. Maybe it belongs on the documentation for --move and --copy instead? It's sort of mentioned in the text at the top describing the -m/-M and -c/-C options, though it's not clear from that text what actually happens to the existing copy of <newbranch> if one uses --force. If we could include a better description of what happens to the existing branch when one uses --force, that'd be nice.

>
>  --sort=<key>::
>         Sort based on the key given. Prefix `-` to sort in descending
>