| Message ID | 3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | branch: rework the descriptions of rename and copy operations | expand |
Hey Dragan (I’m adding some Cc from the previous round) On Thu, Feb 15, 2024, at 19:42, Dragan Simic 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. Excellent. > > 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 Since this is a one-patch series, it wasn’t clear to me what “subsequent improvements” was referring to without following the links. By following the links it looks like plans have been made to improve this man page further. Maybe the commit message could either state this intent more assertively or commit to it less (like “we might in the future…”)? So that the links become supplementary information instead of seemingly filling in some blanks. (If I read this part correctly.) > --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 I had to read the first sentence a few times in order to understand what the “which” part was saying (which seems to come from [1] by Junio). How about letting it trail the sentence? « Rename an existing branch `<oldbranch>` to `<newbranch>`, with `<oldbranch>` defaulting to the current branch if not specified.
Hello Kristoffer, On 2024-02-15 20:28, Kristoffer Haugsbakk wrote: > (I’m adding some Cc from the previous round) Thanks, I realised that to be missing like two seconds after sending the patch to the list. :/ > On Thu, Feb 15, 2024, at 19:42, Dragan Simic 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. > > Excellent. Thanks, I'm glad that you like it. :) >> 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 > > Since this is a one-patch series, it wasn’t clear to me what > “subsequent > improvements” was referring to without following the links. By > following > the links it looks like plans have been made to improve this man page > further. Maybe the commit message could either state this intent more > assertively or commit to it less (like “we might in the future…”)? So > that the links become supplementary information instead of seemingly > filling in some blanks. > > (If I read this part correctly.) It refers to the already planned further rework of the git-branch(1) man page, which I intend to follow, but also leaves a TODO note to anyone else looking at the repository history, in case I end up not following the plan for some reason. I hope this makes it more clear. >> --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 > > I had to read the first sentence a few times in order to understand > what > the “which” part was saying (which seems to come from [1] by Junio). > How > about letting it trail the sentence? > > « Rename an existing branch `<oldbranch>` to `<newbranch>`, with > `<oldbranch>` defaulting to the current branch if not specified. Makes sense, maybe even something like this for the v2: Rename an existing branch <oldbranch> to <newbranch>; if not specified, <oldbranch> defaults to the current branch. >
"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes: > (If I read this part correctly.) > >> --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 > > I had to read the first sentence a few times in order to understand what > the “which” part was saying (which seems to come from [1] by Junio). How > about letting it trail the sentence? > > « Rename an existing branch `<oldbranch>` to `<newbranch>`, with > `<oldbranch>` defaulting to the current branch if not specified. Yeah, insertion of "if not specified" in the middle made the resulting text unnecessarily hard to follow, and moving it to the end is a fine fix. But I think we can just drop it (in other words, we already said "defaulting to" and that should be sufficient). >> + 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. > > “the files” refers to the branch configuration and the reflog? People > who read the man pages might not know that the reflogs are implemented > as files and get tripped up. Maybe “to overwrite” could be left > unstated? Yeah, "overwrite the files in existing branch" can be mislead in other ways, including "in a similar way that 'checkout -f <other>' can overwrite the files with local modifications in the working tree with the <other> branch we are switching to". We'd be better off not mentioning files at all [*]. ... but you can use ... to clobber an existing `<newbranch>`. would be sufficient. If the verb "clobber" is unfamiliar to some readers, "overwrite" is also fine. The most important part from the end-user's point of view is that whatever data associated with the name <newbranch> is now gone, and replaced by what was associated with the name <oldbranch>. How we stored such data associated with each branch is immaterial. Side note: Especially because we are not married to the files backend that stores one file per branch under .git/logs/refs/heads/ and .git/refs/heads/ directories forever. With reftable backend, there is no such files specific to <newbranch> to be overwritten. Another thing. The existence of a <newbranch> is not the only case we fail "git branch -m [<oldbranch>] <newbranch>", but the mention of this particular safety valve is to tell readers that forcing with `-M` is how to override the safety. We want to be absolutely clear that we are not trying to exhaustively enumerate failure modes [*] to our readers, and I am not sure if we succeeded in the proposed text. Side note: In other words, there are other ways the command can fail, and `-M` may not be a way to "fix" these failures. > This patch also drops this part. Shouldn’t this be noted? > > « , and a reflog entry is created to remember the branch renaming. > > Right now it looks like (reads like) the reflog is moved and an entry is > not made about it. True. This was missing in my "or something like that" illustration and the patch copies without checking the original. It should be resurrected. Thanks, both for writing and carefully reading. Removal of <newbranch> and <oldbranch> from the OPTIONS enumaration is really good, too.
Hello Junio, On 2024-02-15 21:41, Junio C Hamano wrote: > "Kristoffer Haugsbakk" <code@khaugsbakk.name> writes: >> (If I read this part correctly.) >> >>> --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 >> >> I had to read the first sentence a few times in order to understand >> what >> the “which” part was saying (which seems to come from [1] by Junio). >> How >> about letting it trail the sentence? >> >> « Rename an existing branch `<oldbranch>` to `<newbranch>`, with >> `<oldbranch>` defaulting to the current branch if not specified. > > Yeah, insertion of "if not specified" in the middle made the > resulting text unnecessarily hard to follow, and moving it to the > end is a fine fix. But I think we can just drop it (in other words, > we already said "defaulting to" and that should be sufficient). This is what seems most readable to me: Rename an existing branch `<oldbranch>` to `<newbranch>`; if left unspecified, `<oldbranch>` defaults to the current branch. >>> + 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. >> >> “the files” refers to the branch configuration and the reflog? People >> who read the man pages might not know that the reflogs are implemented >> as files and get tripped up. Maybe “to overwrite” could be left >> unstated? > > Yeah, "overwrite the files in existing branch" can be mislead in > other ways, including "in a similar way that 'checkout -f <other>' > can overwrite the files with local modifications in the working tree > with the <other> branch we are switching to". We'd be better off > not mentioning files at all [*]. > > ... but you can use ... to clobber an existing `<newbranch>`. > > would be sufficient. If the verb "clobber" is unfamiliar to some > readers, "overwrite" is also fine. The most important part from the > end-user's point of view is that whatever data associated with the > name <newbranch> is now gone, and replaced by what was associated > with the name <oldbranch>. How we stored such data associated with > each branch is immaterial. > > Side note: Especially because we are not married to the > files backend that stores one file per branch under > .git/logs/refs/heads/ and .git/refs/heads/ directories > forever. With reftable backend, there is no such files > specific to <newbranch> to be overwritten. To me, using "clobber" actually doesn't make it more clear. How about wording it this way: 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. To me, "overwriting an existing branch" means something like "deleting an existing branch first, before doing anything else". Just like in case of overwriting an existing file, which gets deleted first, which most users are familiar with. On the other hand, "overwriting the contents of an existing branch", at least to me, means that the branch isn't deleted first, but the new branch is "layered" onto it instead, overwriting some or all of its contents. Additionally, "its contents" removes the direct link between the files and the branches, which should make the description future proof. > Another thing. The existence of a <newbranch> is not the only case > we fail "git branch -m [<oldbranch>] <newbranch>", but the mention > of this particular safety valve is to tell readers that forcing with > `-M` is how to override the safety. We want to be absolutely clear > that we are not trying to exhaustively enumerate failure modes [*] > to our readers, and I am not sure if we succeeded in the proposed > text. > > Side note: In other words, there are other ways the command > can fail, and `-M` may not be a way to "fix" these failures. > >> This patch also drops this part. Shouldn’t this be noted? >> >> « , and a reflog entry is created to remember the branch renaming. >> >> Right now it looks like (reads like) the reflog is moved and an entry >> is >> not made about it. > > True. This was missing in my "or something like that" illustration > and the patch copies without checking the original. It should be > resurrected. Already brought this back for the v2. It was omitted in the v1 by an honest mistake. > Thanks, both for writing and carefully reading. Removal of > <newbranch> and <oldbranch> from the OPTIONS enumaration is really > good, too. I'm glad that you're happy with the improvements so far. :)
On 15-feb-2024 19:42:32, Dragan Simic wrote: > Move the descriptions of the <oldbranch> and <newbranch> arguments to the > descriptions of the branch rename and copy operations, where they naturally > belong. Thank you Dragan for working on this. Let me chime in just to say that maybe another terms could be considered here; like: "<branchname>" and "<newbranchname>" (maybe too long...) or so. I have no problem with the current terms, but "<branchname>" can be a sensible choice here as it is already being used for other commands where, and this may help overall, the consideration: "if ommited, the current branch is considered" also applies. > 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@manjaro.org> > --- > > 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@manjaro.org/T/#u > > Documentation/git-branch.txt | 44 +++++++++++++++--------------------- > 1 file changed, 18 insertions(+), 26 deletions(-) > > 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 > + 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
Rubén Justo <rjusto@gmail.com> writes: > On 15-feb-2024 19:42:32, Dragan Simic wrote: > >> Move the descriptions of the <oldbranch> and <newbranch> arguments to the >> descriptions of the branch rename and copy operations, where they naturally >> belong. > > Thank you Dragan for working on this. > > Let me chime in just to say that maybe another terms could be considered > here; like: "<branchname>" and "<newbranchname>" (maybe too long...) or > so. > > I have no problem with the current terms, but "<branchname>" can be a > sensible choice here as it is already being used for other commands > where, and this may help overall, the consideration: "if ommited, the > current branch is considered" also applies. Actually, we should go in the opposite direction. When the use of names are localized in a narrower context, they can be shortened without losing clarity. For example: -m [<old>] <new>:: rename the <old> branch (defaults to the current one) to <new>. is just as clear as the same description with <oldbranch> and <newbranch>. With the original text without any of the suggested changes, <oldbranch> and <newbranch> appeared very far from the context they are used in (i.e. the description for -m and -c), and it may have helped readers to tell that these are names of branches. But if the context is clear that we are talking about "renaming" branches, there is not as much added benefit to say "branch" in these names as in the current text.
Hello Ruben and Junio, On 2024-02-15 22:52, Rubén Justo wrote: > On 15-feb-2024 19:42:32, Dragan Simic wrote: > >> Move the descriptions of the <oldbranch> and <newbranch> arguments to >> the >> descriptions of the branch rename and copy operations, where they >> naturally >> belong. > > Thank you Dragan for working on this. Thank you, and everyone else, for the reviews and suggestions. > Let me chime in just to say that maybe another terms could be > considered > here; like: "<branchname>" and "<newbranchname>" (maybe too long...) > or > so. > > I have no problem with the current terms, but "<branchname>" can be a > sensible choice here as it is already being used for other commands > where, and this may help overall, the consideration: "if ommited, the > current branch is considered" also applies. Actually, I'd agree with Junio's reply that suggested using even shorter terms. Just like "<oldbranch>" and "<newbranch>" can safely be shortened to "<old>" and "<new>", respectively, "<branchname>" can also be shortened to "<name>". It's all about the context, which is improved by moving the descriptions of the arguments closer to the descriptions of the commands. Though, I'd prefer that we keep "<oldbranch>" and "<newbranch>" (and "<branchname>") for now, for the sake of consistency, and I'd get them shortened in the future patches. >> 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@manjaro.org> >> --- >> >> 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@manjaro.org/T/#u >> >> Documentation/git-branch.txt | 44 >> +++++++++++++++--------------------- >> 1 file changed, 18 insertions(+), 26 deletions(-) >> >> 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 >> + 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
On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic <dsimic@manjaro.org> 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@manjaro.org> > --- > > 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@manjaro.org/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 >
Hello Kyle, On 2024-02-15 23:31, Kyle Lippincott wrote: > On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic <dsimic@manjaro.org> > 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@manjaro.org> >> --- >> >> 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@manjaro.org/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. Thank you, I'm glad that you like it. :) >> 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. In this case, I went with following the intersentence spacing used in the surrounding text. Though, my brain and muscle memory are kind of hardcoded to use double spacing, which may not be as prevalent as a while ago, but IMHO makes reading text rendered using a fixed-width font much easier. I can adjust if needed, of course. >> + 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 >>
On Thu, Feb 15, 2024 at 2:38 PM Dragan Simic <dsimic@manjaro.org> wrote: > > Hello Kyle, > > On 2024-02-15 23:31, Kyle Lippincott wrote: > > On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic <dsimic@manjaro.org> > > 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@manjaro.org> > >> --- > >> > >> 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@manjaro.org/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. > > Thank you, I'm glad that you like it. :) > > >> 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. > > In this case, I went with following the intersentence spacing used in > the surrounding text. Though, my brain and muscle memory are kind of > hardcoded to use double spacing, which may not be as prevalent as a > while > ago, but IMHO makes reading text rendered using a fixed-width font much > easier. I can adjust if needed, of course. No need to adjust if I'm the only one mentioning it. I'm very new to the project, so please don't take my style nits as any sort of mandate, since I'm the one that's most likely to be miscalibrated. :) > > >> + 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 > >>
On 2024-02-15 23:56, Kyle Lippincott wrote: > On Thu, Feb 15, 2024 at 2:38 PM Dragan Simic <dsimic@manjaro.org> > wrote: >> On 2024-02-15 23:31, Kyle Lippincott wrote: >> > 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. >> >> In this case, I went with following the intersentence spacing used in >> the surrounding text. Though, my brain and muscle memory are kind of >> hardcoded to use double spacing, which may not be as prevalent as a >> while >> ago, but IMHO makes reading text rendered using a fixed-width font >> much >> easier. I can adjust if needed, of course. > > No need to adjust if I'm the only one mentioning it. I'm very new to > the project, so please don't take my style nits as any sort of > mandate, since I'm the one that's most likely to be miscalibrated. :) Basically, when it comes to the intersentence spacing, it seems that double spacing has lost its popularity over time. It originates from the old times when mechanical typewriters were used, which most people probably don't even remember these days. :)
On 15-feb-2024 14:13:31, Junio C Hamano wrote: > Rubén Justo <rjusto@gmail.com> writes: > > > On 15-feb-2024 19:42:32, Dragan Simic wrote: > > > >> Move the descriptions of the <oldbranch> and <newbranch> arguments to the > >> descriptions of the branch rename and copy operations, where they naturally > >> belong. > > > > Thank you Dragan for working on this. > > > > Let me chime in just to say that maybe another terms could be considered > > here; like: "<branchname>" and "<newbranchname>" (maybe too long...) or > > so. > > > > I have no problem with the current terms, but "<branchname>" can be a > > sensible choice here as it is already being used for other commands > > where, and this may help overall, the consideration: "if ommited, the > > current branch is considered" also applies. > > Actually, we should go in the opposite direction. When the use of > names are localized in a narrower context, they can be shortened > without losing clarity. I did not mean to have longer terms, sorry for that. I was thinking more in the synopsis: 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<branchname>] <new> 'git branch' (-c | -C) [<branchname>] <new> 'git branch' (-d | -D) [-r] <branchname>... 'git branch' --edit-description [<branchname>] To have more uniformity in the terms, which can be beneficial to the user. We don't say that "--edit-description" defaults to the current branch; It is assumed. Perhaps we can take advantage of that assumption in -m|-c too. Of course, there is no need (perhaps counterproductive) to say "branch" if the context makes it clear it is referring to a branch. > For example: > > -m [<old>] <new>:: > rename the <old> branch (defaults to the current one) to > <new>. > > is just as clear as the same description with <oldbranch> and > <newbranch>. With the original text without any of the suggested > changes, <oldbranch> and <newbranch> appeared very far from the > context they are used in (i.e. the description for -m and -c), and > it may have helped readers to tell that these are names of branches. > But if the context is clear that we are talking about "renaming" > branches, there is not as much added benefit to say "branch" in > these names as in the current text.
On 15-feb-2024 23:27:59, Dragan Simic wrote: > Hello Ruben and Junio, > > On 2024-02-15 22:52, Rubén Justo wrote: > > On 15-feb-2024 19:42:32, Dragan Simic wrote: > > > > > Move the descriptions of the <oldbranch> and <newbranch> arguments > > > to the > > > descriptions of the branch rename and copy operations, where they > > > naturally > > > belong. > > > > Thank you Dragan for working on this. > > Thank you, and everyone else, for the reviews and suggestions. > > > Let me chime in just to say that maybe another terms could be considered > > here; like: "<branchname>" and "<newbranchname>" (maybe too long...) or > > so. > > > > I have no problem with the current terms, but "<branchname>" can be a > > sensible choice here as it is already being used for other commands > > where, and this may help overall, the consideration: "if ommited, the > > current branch is considered" also applies. > > Actually, I'd agree with Junio's reply that suggested using even > shorter terms. Me too :-) > Just like "<oldbranch>" and "<newbranch>" can safely > be shortened to "<old>" and "<new>", respectively, "<branchname>" > can also be shortened to "<name>". > > It's all about the context, which is improved by moving the descriptions > of the arguments closer to the descriptions of the commands. Your series is an improvement in that respect. Thank you. > > Though, I'd prefer that we keep "<oldbranch>" and "<newbranch>" (and > "<branchname>") for now, for the sake of consistency, and I'd get them > shortened in the future patches. Nice!
On 2024-02-16 00:34, Rubén Justo wrote: > On 15-feb-2024 14:13:31, Junio C Hamano wrote: >> Rubén Justo <rjusto@gmail.com> writes: >>> On 15-feb-2024 19:42:32, Dragan Simic wrote: >>> Let me chime in just to say that maybe another terms could be >>> considered >>> here; like: "<branchname>" and "<newbranchname>" (maybe too long...) >>> or >>> so. >>> >>> I have no problem with the current terms, but "<branchname>" can be a >>> sensible choice here as it is already being used for other commands >>> where, and this may help overall, the consideration: "if ommited, the >>> current branch is considered" also applies. >> >> Actually, we should go in the opposite direction. When the use of >> names are localized in a narrower context, they can be shortened >> without losing clarity. > > I did not mean to have longer terms, sorry for that. > > I was thinking more in the synopsis: > > 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) > [<branchname>] > 'git branch' --unset-upstream [<branchname>] > 'git branch' (-m | -M) [<branchname>] <new> > 'git branch' (-c | -C) [<branchname>] <new> > 'git branch' (-d | -D) [-r] <branchname>... > 'git branch' --edit-description [<branchname>] > > To have more uniformity in the terms, which can be beneficial to the > user. Here's what I think the example from above should eventually look like: 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<name>] 'git branch' --unset-upstream [<name>] 'git branch' (-m | -M) [<old>] <new> 'git branch' (-c | -C) [<old>] <new> 'git branch' (-d | -D) [-r] <name>... 'git branch' --edit-description [<name>] Though, it's something to be left for future patches, which will move more argument descriptions to the respective command descriptions. > We don't say that "--edit-description" defaults to the current branch; > It is assumed. Perhaps we can take advantage of that assumption in > -m|-c too. We don't say that yet, :) because the description of the command for editing branch descriptions is detached from the description of its arguments. The plan is to move all of them together. > Of course, there is no need (perhaps counterproductive) to say "branch" > if the context makes it clear it is referring to a branch.
On 16-feb-2024 04:32:10, Dragan Simic wrote: > On 2024-02-16 00:34, Rubén Justo wrote: > > On 15-feb-2024 14:13:31, Junio C Hamano wrote: > > > Rubén Justo <rjusto@gmail.com> writes: > > > > On 15-feb-2024 19:42:32, Dragan Simic wrote: > > > > Let me chime in just to say that maybe another terms could be > > > > considered > > > > here; like: "<branchname>" and "<newbranchname>" (maybe too > > > > long...) or > > > > so. > > > > > > > > I have no problem with the current terms, but "<branchname>" can be a > > > > sensible choice here as it is already being used for other commands > > > > where, and this may help overall, the consideration: "if ommited, the > > > > current branch is considered" also applies. > > > > > > Actually, we should go in the opposite direction. When the use of > > > names are localized in a narrower context, they can be shortened > > > without losing clarity. > > > > I did not mean to have longer terms, sorry for that. > > > > I was thinking more in the synopsis: > > > > 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) > > [<branchname>] > > 'git branch' --unset-upstream [<branchname>] > > 'git branch' (-m | -M) [<branchname>] <new> > > 'git branch' (-c | -C) [<branchname>] <new> > > 'git branch' (-d | -D) [-r] <branchname>... > > 'git branch' --edit-description [<branchname>] > > > > To have more uniformity in the terms, which can be beneficial to the > > user. > > Here's what I think the example from above should eventually look like: > > 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<name>] > 'git branch' --unset-upstream [<name>] Well, my point was not about new terms in this series, but to see if the idea of reusing an existing one might be of interest. I find it interesting to have common terms like "<commit>" "<path>", "<envvar>"... This builds intuition in the user, making it easier to grasp the meaning of a term, which refers to a similar /thing/, regardless of being used in different contexts. And in turn, it can also help to better understand the context. Side note: My gut tells me that my patch 5aea3955bc (branch: clarify <oldbranch> term, 2024-01-06) which was originated by a report [1] of a user who found the documentation confusing, would have been less likely to happen (the report and consequently my patch) if "<branchname>" had been used instead of "<oldbranch>" in the documentation. Not because "<branchname>" is a better name, but because it is already being used in other commands with a clearer meaning of: "if not specified it defaults to the current branch". And because of that a user might have be able to fill the gaps in -m|-c. Of course this is based on my intuition, which I know is seriously biased. [1] https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/ And not only can it be of help to the user, but also to developers (or reviewers) when documenting new commands or options; because there is no need to search for a, maybe new, name if there is one that is consolidated. Perhaps, less names can also improve the lives of translators by making it easier to reuse some of the translations. As I write, I realise that all this probably belongs to CodingGuideLines or similar. Or maybe it is too academic to be practical. I Dunno. > 'git branch' (-m | -M) [<old>] <new> > 'git branch' (-c | -C) [<old>] <new> > 'git branch' (-d | -D) [-r] <name>... > 'git branch' --edit-description [<name>] So, to your proposal: it does not make things worse, and it reuses terms that are already used elsewhere: $ for a in '<new>' '<old>' '<name>'; do echo $a $(git grep --no-line-number -E "$a" v2.44.0-rc1 -- Documentation/git-*.txt | wc -l); done <new> 7 <old> 7 <name> 147 But based on the idea I've just described, IMHO the user might not easily find the similarities in <old> with <name>: > 'git branch' (-c | -C) [<old>] <new> > 'git branch' (-d | -D) [-r] <name>... At least, not better than with <oldbranch> and <branchname>. And it won't be easy either with <name> and other man pages. For example we have: $ git grep -E 'git checkout.*(new-)?branch' Documentation/git-checkout.txt Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [<branch>] Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach [<branch>] Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] Documentation/git-checkout.txt:'git checkout' [<branch>]:: Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch> Documentation/git-checkout.txt:'git checkout' -b|-B <new-branch> [<start-point>]:: Documentation/git-checkout.txt:$ git checkout <branch> Documentation/git-checkout.txt:'git checkout' --detach [<branch>]:: Documentation/git-checkout.txt: "git branch" with "-f" followed by "git checkout" of that branch; Documentation/git-checkout.txt:$ git checkout -b <branch> --track <remote>/<branch> On the names chosen, the risk of bikesheeding is high and there is nothing wrong here, so it is way better to let you work. You have taken the initiative from Junios's response to my patch, so thank you for that. > Though, it's something to be left for future patches, which will move > more argument descriptions to the respective command descriptions. > > > We don't say that "--edit-description" defaults to the current branch; > > It is assumed. Perhaps we can take advantage of that assumption in > > -m|-c too. > > We don't say that yet, :) Yeah, but maybe we can do it without writing it down :) > because the description of the command for > editing branch descriptions is detached from the description of its > arguments. The plan is to move all of them together. > > > Of course, there is no need (perhaps counterproductive) to say "branch" > > if the context makes it clear it is referring to a branch.
Hello Ruben, On 2024-02-17 15:58, Rubén Justo wrote: > On 16-feb-2024 04:32:10, Dragan Simic wrote: >> Here's what I think the example from above should eventually look >> like: >> >> 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) >> [<name>] >> 'git branch' --unset-upstream [<name>] > > Well, my point was not about new terms in this series, but to see if > the > idea of reusing an existing one might be of interest. Good point, ensuring such consistency would be really good. > I find it interesting to have common terms like "<commit>" "<path>", > "<envvar>"... ... or "<branch>". :) > This builds intuition in the user, making it easier to grasp the > meaning > of a term, which refers to a similar /thing/, regardless of being used > in different contexts. And in turn, it can also help to better > understand the context. Agreed, consistency is good. > Side note: My gut tells me that my patch 5aea3955bc (branch: > clarify <oldbranch> term, 2024-01-06) which was originated by a > report [1] of a user who found the documentation confusing, would > have been less likely to happen (the report and consequently my > patch) if "<branchname>" had been used instead of "<oldbranch>" in > the documentation. Not because "<branchname>" is a better name, > but because it is already being used in other commands with a > clearer meaning of: "if not specified it defaults to the current > branch". And because of that a user might have be able to fill > the > gaps in -m|-c. Of course this is based on my intuition, which I > know is seriously biased. > > [1] > https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/ After thinking a bit more about the whole thing, I think that using "<branch>" instead of "<name>" or "<branchname>" would be our best choice. It would be simple, direct and clear. Regarding the branch copy and rename operations and their argument names, perhaps the following would be a good choice: --copy [<branch>] <destination> --move [<branch>] <destination> It would clearly reflect the nature of the performed operations, while still using "<branch>" consistently, this time to refer to the source branch. Using "<destination>" to select the destination name should be pretty much self-descriptive, if you agree. Of course, I'll get back to this later in this message. > And not only can it be of help to the user, but also to developers (or > reviewers) when documenting new commands or options; because there is > no need to search for a, maybe new, name if there is one that is > consolidated. > > Perhaps, less names can also improve the lives of translators by making > it easier to reuse some of the translations. Perhaps. That should be another example of the long-term benefits achieved through improved consistency. >> 'git branch' (-m | -M) [<old>] <new> >> 'git branch' (-c | -C) [<old>] <new> >> 'git branch' (-d | -D) [-r] <name>... >> 'git branch' --edit-description [<name>] > > So, to your proposal: it does not make things worse, and it reuses > terms that are already used elsewhere: > > $ for a in '<new>' '<old>' '<name>'; do echo $a $(git grep > --no-line-number -E "$a" v2.44.0-rc1 -- Documentation/git-*.txt | wc > -l); done > <new> 7 > <old> 7 > <name> 147 > > But based on the idea I've just described, IMHO the user might not > easily find the similarities in <old> with <name>: I agree after thinking about the whole thing a bit more. > And it won't be easy either with <name> and other man pages. For > example we have: > > $ git grep -E 'git checkout.*(new-)?branch' > Documentation/git-checkout.txt > Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] > [<branch>] > Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach > [<branch>] > Documentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] > [[-b|-B|--orphan] <new-branch>] [<start-point>] > Documentation/git-checkout.txt:'git checkout' [<branch>]:: > Documentation/git-checkout.txt:$ git checkout -b <branch> --track > <remote>/<branch> > Documentation/git-checkout.txt:'git checkout' -b|-B <new-branch> > [<start-point>]:: > Documentation/git-checkout.txt:$ git checkout <branch> > Documentation/git-checkout.txt:'git checkout' --detach [<branch>]:: > Documentation/git-checkout.txt: "git branch" with "-f" followed > by "git checkout" of that branch; > Documentation/git-checkout.txt:$ git checkout -b <branch> --track > <remote>/<branch> I'd say this solidifies "<branch>" as, hopefully, our best choice, as already proposed above. > On the names chosen, the risk of bikesheeding is high and there is > nothing wrong here, so it is way better to let you work. You have > taken > the initiative from Junios's response to my patch, so thank you for > that. I hope we'll eventually produce a great git-branch(1) man page together. After that's completed, I have some more plans for improving git-branch, by introducing some additional operations. >> > We don't say that "--edit-description" defaults to the current branch; >> > It is assumed. Perhaps we can take advantage of that assumption in >> > -m|-c too. >> >> We don't say that yet, :) > > Yeah, but maybe we can do it without writing it down :) Maybe, :) but again, spending a few additional words to describe that might actually be beneficial. We'll see how it goes.
Dragan Simic <dsimic@manjaro.org> writes: > Regarding the branch copy and rename operations and their argument > names, perhaps the following would be a good choice: > > --copy [<branch>] <destination> > --move [<branch>] <destination> > > It would clearly reflect the nature of the performed operations, while > still using "<branch>" consistently, this time to refer to the source > branch. Using "<destination>" to select the destination name should > be pretty much self-descriptive, if you agree. Awful. While I was skimming the messages without reading the Subject line (hence without realizing that this is about improving the existing documentation and not adding new features), I thought that these two are about moving branch to a remote repository that is named with <destination>. My advice would be to stick to <old> vs <new> that contrasts well. Thanks.
Hello Junio, On 2024-02-19 20:49, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >> Regarding the branch copy and rename operations and their argument >> names, perhaps the following would be a good choice: >> >> --copy [<branch>] <destination> >> --move [<branch>] <destination> >> >> It would clearly reflect the nature of the performed operations, while >> still using "<branch>" consistently, this time to refer to the source >> branch. Using "<destination>" to select the destination name should >> be pretty much self-descriptive, if you agree. > > Awful. While I was skimming the messages without reading the > Subject line (hence without realizing that this is about improving > the existing documentation and not adding new features), I thought > that these two are about moving branch to a remote repository that > is named with <destination>. > > My advice would be to stick to <old> vs <new> that contrasts well. I appreciate the directness and honesty. How about using "<oldbranch>" and "<newbranch>" instead, which, although more wordy, would be more consistent with "<branch>" that's used in a number of other places? Such consistency should make the users recognize the arguments better at first glance.
Dragan Simic <dsimic@manjaro.org> writes: >> My advice would be to stick to <old> vs <new> that contrasts well. > > I appreciate the directness and honesty. How about using "<oldbranch>" > and "<newbranch>" instead, which, although more wordy, would be more > consistent with "<branch>" that's used in a number of other places? I have slight aversion to non-words like "oldbranch" (not "old-branch"), but not that much. Quite honestly, in a document whose primary topic is "branch", I doubt that repeating "branch" all over the place would be the consistency we should be aiming for in the first place, when it is clear from the context that we are talking about branches. The updates we are making to Documentation/git-branch.txt that (1) slims wordy description of different modes in the DESCRIPTION section, (2) make option description of "-m" mention what argument(s) the option takes, and (3) rmove standalone <newbranch> and <oldbranch> description are all about making the necessary piece of information easier to find in one place (namely, the option description where "-m [<one branch name>] [<the other branch name>]" is described) without having to jump around all over in the documentation, so in that sense, I would think the way to go is to aim for brevity that takes advantage of the local context.
On 20-feb-2024 10:24:25, Junio C Hamano wrote: > I have slight aversion to non-words like "oldbranch" (not > "old-branch"), but not that much. I also have problems with <old...>. What's the reference in "old"? Prior to the restructuring of the whole file, we should probably do: ---- >8 --------- >8 --------- >8 --------- >8 ------ Subject: [PATCH] branch: adjust documentation Adjust the terms we use in Documentation/git-branch.txt to what we say in CodingGuideLines: If a placeholder has multiple words, they are separated by dashes: <new-branch-name> --template=<template-directory> Best viewed with --word-diff. Signed-off-by: Rubén Justo <rjusto@gmail.com> --- Documentation/git-branch.txt | 57 +++++++++++++++++------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0b08442932..d834d89a7f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -17,13 +17,13 @@ SYNOPSIS [(-r | --remotes) | (-a | --all)] [--list] [<pattern>...] 'git branch' [--track[=(direct|inherit)] | --no-track] [-f] - [--recurse-submodules] <branchname> [<start-point>] -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] -'git branch' --unset-upstream [<branchname>] -'git branch' (-m | -M) [<oldbranch>] <newbranch> -'git branch' (-c | -C) [<oldbranch>] <newbranch> -'git branch' (-d | -D) [-r] <branchname>... -'git branch' --edit-description [<branchname>] + [--recurse-submodules] <new-branch> [<start-point>] +'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branch>] +'git branch' --unset-upstream [<branch>] +'git branch' (-m | -M) [<branch>] <new-branch> +'git branch' (-c | -C) [<branch>] <new-branch> +'git branch' (-d | -D) [-r] <branch>... +'git branch' --edit-description [<branch>] DESCRIPTION ----------- @@ -53,7 +53,7 @@ branches not merged into the named commit will be listed. If the <commit> argument is missing it defaults to `HEAD` (i.e. the tip of the current branch). -The command's second form creates a new branch head named <branchname> +The command's second form creates a new branch head named <branch> which points to the current `HEAD`, or <start-point> if given. As a special case, for <start-point>, you may use `"A...B"` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. Note that this will create the new branch, but it will not switch the -working tree to it; use "git switch <newbranch>" to switch to the +working tree to it; use "git switch" to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the @@ -72,17 +72,17 @@ 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 +With a `-m` or `-M` option, <branch> will be renamed to <new-branch>. +If <branch> had a corresponding reflog, it is renamed to match +<new-branch>, and a reflog entry is created to remember the branch +renaming. If <new-branch> 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 +With a `-d` or `-D` option, `<branch>` 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. @@ -107,7 +107,7 @@ OPTIONS --create-reflog:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date - based sha1 expressions such as "<branchname>@\{yesterday}". + based sha1 expressions such as "<branch>@\{yesterday}". Note that in non-bare repositories, reflogs are usually enabled by default by the `core.logAllRefUpdates` config option. The negated form `--no-create-reflog` only overrides an earlier @@ -116,7 +116,7 @@ OPTIONS -f:: --force:: - Reset <branchname> to <start-point>, even if <branchname> exists + Reset <branch> to <start-point>, even if <branch> exists already. Without `-f`, 'git branch' refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status, or whether it even @@ -124,8 +124,8 @@ OPTIONS `-m` (or `--move`), allow renaming the branch even if the new branch name already exists, the same applies for `-c` (or `--copy`). + -Note that 'git branch -f <branchname> [<start-point>]', even with '-f', -refuses to change an existing branch `<branchname>` that is checked out +Note that 'git branch -f <branch> [<start-point>]', even with '-f', +refuses to change an existing branch `<branch>` that is checked out in another worktree linked to the same repository. -m:: @@ -255,7 +255,7 @@ how the `branch.<name>.remote` and `branch.<name>.merge` options are used. linkgit:git-config[1]. Currently, only branch creation is supported. + -When used in branch creation, a new branch <branchname> will be created +When used in branch creation, a new branch <branch> will be created in the superproject and all of the submodules in the superproject's <start-point>. In submodules, the branch will point to the submodule commit in the superproject's <start-point> but the branch's tracking @@ -270,12 +270,12 @@ superproject's "origin/main", but tracks the submodule's "origin/main". -u <upstream>:: --set-upstream-to=<upstream>:: - Set up <branchname>'s tracking information so <upstream> is - considered <branchname>'s upstream branch. If no <branchname> + Set up <branch>'s tracking information so <upstream> is + considered <branch>'s upstream branch. If no <branch> is specified, then it defaults to the current branch. --unset-upstream:: - Remove the upstream information for <branchname>. If no branch + Remove the upstream information for <branch>. If no branch is specified it defaults to the current branch. --edit-description:: @@ -300,24 +300,21 @@ superproject's "origin/main", but tracks the submodule's "origin/main". Only list branches whose tips are not reachable from the specified commit (HEAD if not specified). Implies `--list`. -<branchname>:: +<branch>:: The name of the branch to create or delete. The new branch name must pass all checks defined by linkgit:git-check-ref-format[1]. Some of these checks may restrict the characters allowed in a branch name. + If ommited, the current branch will be used instead. <start-point>:: The new branch head will point to this commit. It may be 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. +<new-branch>:: + The name for new branch. The same restrictions as for + <branch> apply. --sort=<key>:: Sort based on the key given. Prefix `-` to sort in descending
On 18-feb-2024 21:38:54, Dragan Simic wrote: > Regarding the branch copy and rename operations and their argument > names, perhaps the following would be a good choice: > > --copy [<branch>] <destination> > --move [<branch>] <destination> > > It would clearly reflect the nature of the performed operations, while > still using "<branch>" consistently, this time to refer to the source > branch. Using "<destination>" to select the destination name should > be pretty much self-descriptive, if you agree. Sorry, but I don't. Actually, I don't see the logic with <destination>. I appreciate your efforts to provide consistency, but the current ones seem better options to me: either <oldbranch> and <newbranch>, or the shortened ones: <old> and <new>. Thanks.
On 2024-02-20 19:24, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >>> My advice would be to stick to <old> vs <new> that contrasts well. >> >> I appreciate the directness and honesty. How about using >> "<oldbranch>" >> and "<newbranch>" instead, which, although more wordy, would be more >> consistent with "<branch>" that's used in a number of other places? > > I have slight aversion to non-words like "oldbranch" (not > "old-branch"), but not that much. > > Quite honestly, in a document whose primary topic is "branch", I > doubt that repeating "branch" all over the place would be the > consistency we should be aiming for in the first place, when it is > clear from the context that we are talking about branches. > > The updates we are making to Documentation/git-branch.txt that (1) > slims wordy description of different modes in the DESCRIPTION > section, (2) make option description of "-m" mention what > argument(s) the option takes, and (3) rmove standalone <newbranch> > and <oldbranch> description are all about making the necessary piece > of information easier to find in one place (namely, the option > description where "-m [<one branch name>] [<the other branch name>]" > is described) without having to jump around all over in the > documentation, so in that sense, I would think the way to go is to > aim for brevity that takes advantage of the local context. It's hard not to agree with the way you laid this out. :) In a nutshell, the way I see it, using "<old>" and "<new>" is also fine. It's also fine with me to use "<name>" instead of "<branch>"; in fact, if we go with "<old>" and "<new>", we should go with "<name>", too.
On 2024-02-20 20:12, Rubén Justo wrote: > On 20-feb-2024 10:24:25, Junio C Hamano wrote: > >> I have slight aversion to non-words like "oldbranch" (not >> "old-branch"), but not that much. > > I also have problems with <old...>. What's the reference in "old"? > > Prior to the restructuring of the whole file, we should probably do: FWIW, I'm perfectly fine with having your patch, available below, applied right now. To me, it would provide a true improvement. > ---- >8 --------- >8 --------- >8 --------- >8 ------ > Subject: [PATCH] branch: adjust documentation > > Adjust the terms we use in Documentation/git-branch.txt to what > we say in CodingGuideLines: > > If a placeholder has multiple words, they are separated by dashes: > <new-branch-name> > --template=<template-directory> > > Best viewed with --word-diff. > > Signed-off-by: Rubén Justo <rjusto@gmail.com> > --- > Documentation/git-branch.txt | 57 +++++++++++++++++------------------- > 1 file changed, 27 insertions(+), 30 deletions(-) > > diff --git a/Documentation/git-branch.txt > b/Documentation/git-branch.txt > index 0b08442932..d834d89a7f 100644 > --- a/Documentation/git-branch.txt > +++ b/Documentation/git-branch.txt > @@ -17,13 +17,13 @@ SYNOPSIS > [(-r | --remotes) | (-a | --all)] > [--list] [<pattern>...] > 'git branch' [--track[=(direct|inherit)] | --no-track] [-f] > - [--recurse-submodules] <branchname> [<start-point>] > -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) > [<branchname>] > -'git branch' --unset-upstream [<branchname>] > -'git branch' (-m | -M) [<oldbranch>] <newbranch> > -'git branch' (-c | -C) [<oldbranch>] <newbranch> > -'git branch' (-d | -D) [-r] <branchname>... > -'git branch' --edit-description [<branchname>] > + [--recurse-submodules] <new-branch> [<start-point>] > +'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branch>] > +'git branch' --unset-upstream [<branch>] > +'git branch' (-m | -M) [<branch>] <new-branch> > +'git branch' (-c | -C) [<branch>] <new-branch> > +'git branch' (-d | -D) [-r] <branch>... > +'git branch' --edit-description [<branch>] > > DESCRIPTION > ----------- > @@ -53,7 +53,7 @@ branches not merged into the named commit will be > listed. If the <commit> > argument is missing it defaults to `HEAD` (i.e. the tip of the current > branch). > > -The command's second form creates a new branch head named <branchname> > +The command's second form creates a new branch head named <branch> > which points to the current `HEAD`, or <start-point> if given. As a > special case, for <start-point>, you may use `"A...B"` as a shortcut > for > the merge base of `A` and `B` if there is exactly one merge base. You > @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which > case it defaults to > `HEAD`. > > Note that this will create the new branch, but it will not switch the > -working tree to it; use "git switch <newbranch>" to switch to the > +working tree to it; use "git switch" to switch to the > new branch. > > When a local branch is started off a remote-tracking branch, Git sets > up the > @@ -72,17 +72,17 @@ 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 > +With a `-m` or `-M` option, <branch> will be renamed to <new-branch>. > +If <branch> had a corresponding reflog, it is renamed to match > +<new-branch>, and a reflog entry is created to remember the branch > +renaming. If <new-branch> 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 > +With a `-d` or `-D` option, `<branch>` 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. > > @@ -107,7 +107,7 @@ OPTIONS > --create-reflog:: > Create the branch's reflog. This activates recording of > all changes made to the branch ref, enabling use of date > - based sha1 expressions such as "<branchname>@\{yesterday}". > + based sha1 expressions such as "<branch>@\{yesterday}". > Note that in non-bare repositories, reflogs are usually > enabled by default by the `core.logAllRefUpdates` config option. > The negated form `--no-create-reflog` only overrides an earlier > @@ -116,7 +116,7 @@ OPTIONS > > -f:: > --force:: > - Reset <branchname> to <start-point>, even if <branchname> exists > + Reset <branch> to <start-point>, even if <branch> exists > already. Without `-f`, 'git branch' refuses to change an existing > branch. > In combination with `-d` (or `--delete`), allow deleting the > branch irrespective of its merged status, or whether it even > @@ -124,8 +124,8 @@ OPTIONS > `-m` (or `--move`), allow renaming the branch even if the new > branch name already exists, the same applies for `-c` (or `--copy`). > + > -Note that 'git branch -f <branchname> [<start-point>]', even with > '-f', > -refuses to change an existing branch `<branchname>` that is checked > out > +Note that 'git branch -f <branch> [<start-point>]', even with '-f', > +refuses to change an existing branch `<branch>` that is checked out > in another worktree linked to the same repository. > > -m:: > @@ -255,7 +255,7 @@ how the `branch.<name>.remote` and > `branch.<name>.merge` options are used. > linkgit:git-config[1]. Currently, only branch creation is > supported. > + > -When used in branch creation, a new branch <branchname> will be > created > +When used in branch creation, a new branch <branch> will be created > in the superproject and all of the submodules in the superproject's > <start-point>. In submodules, the branch will point to the submodule > commit in the superproject's <start-point> but the branch's tracking > @@ -270,12 +270,12 @@ superproject's "origin/main", but tracks the > submodule's "origin/main". > > -u <upstream>:: > --set-upstream-to=<upstream>:: > - Set up <branchname>'s tracking information so <upstream> is > - considered <branchname>'s upstream branch. If no <branchname> > + Set up <branch>'s tracking information so <upstream> is > + considered <branch>'s upstream branch. If no <branch> > is specified, then it defaults to the current branch. > > --unset-upstream:: > - Remove the upstream information for <branchname>. If no branch > + Remove the upstream information for <branch>. If no branch > is specified it defaults to the current branch. > > --edit-description:: > @@ -300,24 +300,21 @@ superproject's "origin/main", but tracks the > submodule's "origin/main". > Only list branches whose tips are not reachable from the > specified commit (HEAD if not specified). Implies `--list`. > > -<branchname>:: > +<branch>:: > The name of the branch to create or delete. > The new branch name must pass all checks defined by > linkgit:git-check-ref-format[1]. Some of these checks > may restrict the characters allowed in a branch name. > + If ommited, the current branch will be used instead. > > <start-point>:: > The new branch head will point to this commit. It may be > 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. > +<new-branch>:: > + The name for new branch. The same restrictions as for > + <branch> apply. > > --sort=<key>:: > Sort based on the key given. Prefix `-` to sort in descending
On 2024-02-20 20:14, Rubén Justo wrote: > On 18-feb-2024 21:38:54, Dragan Simic wrote: > >> Regarding the branch copy and rename operations and their argument >> names, perhaps the following would be a good choice: >> >> --copy [<branch>] <destination> >> --move [<branch>] <destination> >> >> It would clearly reflect the nature of the performed operations, while >> still using "<branch>" consistently, this time to refer to the source >> branch. Using "<destination>" to select the destination name should >> be pretty much self-descriptive, if you agree. > > Sorry, but I don't. Actually, I don't see the logic with > <destination>. No worries, I appreciate the directness. > I appreciate your efforts to provide consistency, but the current ones > seem better options to me: either <oldbranch> and <newbranch>, or the > shortened ones: <old> and <new>. As I wrote a bit earlier, while replying to Junio, using "<old>" and "<new>" (together with "<name>") is fine with me. Though, using "<branch>" and "<new-branch>" is also a very good option, which would additionally avoid introducing "<name>" to replace "<branch>", which I find highly beneficial, because it would provide consistency with the rest of the documentation.
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 + 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
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@manjaro.org> --- 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@manjaro.org/T/#u Documentation/git-branch.txt | 44 +++++++++++++++--------------------- 1 file changed, 18 insertions(+), 26 deletions(-)