On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic <dsimic@xxxxxxxxxxx> 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@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, 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@xxxxxxxxxxx/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 >
