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@xxxxxxxxxxx> --- 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, the version 1 is effectively version 2 of the original patch. The version 1 of the patch 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. The version 2 includes feedback from Kristoffer and Junio, by improving the wording of the opening sentences in the descriptions of branch rename and copy operations, and by mentioning the additional reflog entry created while renaming a branch, which was omitted in the v1 by mistake. [3] https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@xxxxxxxxxxx/T/#u Documentation/git-branch.txt | 51 ++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0b0844293235..d52b5e8dbacd 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,31 @@ 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:: +-m [<oldbranch>] <newbranch>:: +--move [<oldbranch>] <newbranch>:: + Rename an existing branch `<oldbranch>` to `<newbranch>`; if left + unspecified, `<oldbranch>` defaults to the current branch. The + configuration variables for the `<oldbranch>` branch and its reflog + are also renamed appropriately to be used with `<newbranch>`. In + addition, a reflog entry is created to remember the branch renaming. + Renaming fails if branch `<newbranch>` already exists, but `-M` + or `--move --force` can be used to overwrite the contents of the + existing branch `<newbranch>` while renaming. + +-M [<oldbranch>] <newbranch>:: Shortcut for `--move --force`. --c:: ---copy:: - Copy a branch, together with its config and reflog. - --C:: +-c [<oldbranch>] <newbranch>:: +--copy [<oldbranch>] <newbranch>:: + Copy an existing branch `<oldbranch>` to `<newbranch>`; if left + unspecified, `<oldbranch>` defaults to the current branch. 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 `-C` + or `--copy --force` can be used to overwrite the contents of the + existing branch `<newbranch>` while copying. + +-C [<oldbranch>] <newbranch>:: Shortcut for `--copy --force`. --color[=<when>]:: @@ -311,14 +314,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
