[PATCH] Mention default oldbranch in git-branch doc

[PATCH] Mention default oldbranch in git-branch doc

[Clarence "Sparr" Risher via GitGitGadget]

From: "Clarence \"Sparr\" Risher" <sparr0@gmail.com>

`git branch -m` has an optional first argument, the branch to rename.
If omitted, it defaults to the current branch. This behavior is not
currently described in the documentation. While it can be determined
relatively easily through experimentation, and less so through viewing
the source code (builtin/branch.c:897), it is not obvious what such a
command will do when encountered in a less interactive context.

This patch adds one sentence to the git-branch documentation, with
wording based on another optional argument described earlier in the
same doc.

The same behavior applies to -M, -c, and -C, which are all covered by
this same section of the documentation.

Signed-off-by: Clarence Risher <clarence@kira-learning.com>
Signed-off-by: Clarence "Sparr" Risher <sparr0@gmail.com>
---
    Mention default oldbranch in git-branch doc

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1613%2Fsparr%2Fdoc_branch_rename_one_param-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1613/sparr/doc_branch_rename_one_param-v1
Pull-Request: https://github.com/git/git/pull/1613

 Documentation/git-branch.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 4395aa93543..affed1b17a4 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -73,6 +73,7 @@ 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 the <oldbranch> argument is missing it defaults to the current branch.
 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

base-commit: 564d0252ca632e0264ed670534a51d18a689ef5d
-- 
gitgitgadget

Re: [PATCH] Mention default oldbranch in git-branch doc

[Rubén Justo]

On 30-nov-2023 00:24:51, Clarence "Sparr" Risher via GitGitGadget wrote:
> From: "Clarence \"Sparr\" Risher" <sparr0@gmail.com>
> 
> `git branch -m` has an optional first argument, the branch to rename.
> If omitted, it defaults to the current branch. This behavior is not
> currently described in the documentation.

Good catch.

> While it can be determined
> relatively easily through experimentation, and less so through viewing
> the source code (builtin/branch.c:897)

Some people will find it easier by reading the code than through
experimentation ;-)

> it is not obvious what such a
> command will do when encountered in a less interactive context.

Certainly, I agree.

> 
> This patch adds one sentence to the git-branch documentation, with
> wording based on another optional argument described earlier in the
> same doc.
> 
> The same behavior applies to -M, -c, and -C

Good.

> 
> Signed-off-by: Clarence Risher <clarence@kira-learning.com>
> Signed-off-by: Clarence "Sparr" Risher <sparr0@gmail.com>

Are you both?  If that is the case, IMO it is unusual in this project to
have two different signatures for the same person in one commit.

> 
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 4395aa93543..affed1b17a4 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -73,6 +73,7 @@ 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 the <oldbranch> argument is missing it defaults to the current branch.

Sounds good.  But IMHO this information fits better below, where the
term "<oldbranch>" is described.  Something like:

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 4395aa9354..9c17df9f4d 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -312,7 +312,8 @@ 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 to rename.
+       The name of an existing branch to rename or copy.  If this
+       option is omitted, the current branch will be used instead.

Completing while we're here, what we missed when -c was introduced in
52d59cc645 (branch: add a --copy (-c) option to go with --move (-m),
2017-06-18).

>  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
> 
> base-commit: 564d0252ca632e0264ed670534a51d18a689ef5d
> -- 
> gitgitgadget


Thank you for working on this.