[PATCH] Mention default oldbranch in git-branch doc

Clarence Sparr Risher via GitGitGadget· Nov 30, 2023, 00:24 UTC · lore

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

Show changes to Documentation/git-branch.txt +1 −0

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

Rubén Justo· Dec 1, 2023, 01:25 UTC · re: Clarence Sparr Risher via GitGitGadget · lore

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

On 30-nov-2023 00:24:51, Clarence "Sparr" Risher via GitGitGadget wrote:

Show 5 quoted lines

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

Show 6 quoted lines

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

Show 10 quoted lines

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

Show changes to Documentation/git-branch.txt +2 −1

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.

patchMention default oldbranch in git-branch doc