[PATCH] branch: rework the descriptions of rename and copy operations

[PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Kristoffer Haugsbakk]

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.

🔗 1: https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/

> +	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?

Or maybe I just misunderstood this part.

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.

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

> 🔗 1: https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/
> 
>> +	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?
> 
> Or maybe I just misunderstood this part.

Basically, the internal logic just overwrites the files, whatever the
files actually are, and issues warning messages about that.  Frankly,
I'm not sure that having "--force" available is the safest possible 
thing,
but it's already there and needs documenting.

Thus, "the files" refers to just that, the files in the destination
branch that pretty much gets garbled after forced operations.

Perhaps it could be worded like this in the v2:

     ... but you can use `-M` or `--move --force` to overwrite the 
contents
     of the existing branch <newbranch> while renaming.

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

Good point, thanks.  I'll address that in the v2.

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Junio C Hamano]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Junio C Hamano]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Junio C Hamano]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Junio C Hamano]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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

[PATCH] branch: adjust documentation

[Rubén Justo]

Adjust the placeholders 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 | 54 +++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 29 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 0b08442932..489507e25f 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 <new-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 <new-branch>" 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 <new-branch> to <start-point>, even if <new-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 <new-branch> [<start-point>]', even with '-f',
+refuses to change an existing branch `<new-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 <new-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,8 +300,8 @@ 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>::
-	The name of the branch to create or delete.
+<new-branch>::
+	The name of the branch to create.
 	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.
@@ -311,14 +311,10 @@ 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>::
+<branch>::
 	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
-- 
2.44.0.rc2

Re: [PATCH] branch: adjust documentation

[Dragan Simic]

On 2024-02-20 21:25, Rubén Justo wrote:
> Adjust the placeholders 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>

Looking good to me!

Reviewed-by: Dragan Simic <dsimic@manjaro.org>

> ---
> 
>  Documentation/git-branch.txt | 54 +++++++++++++++++-------------------
>  1 file changed, 25 insertions(+), 29 deletions(-)
> 
> diff --git a/Documentation/git-branch.txt 
> b/Documentation/git-branch.txt
> index 0b08442932..489507e25f 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 <new-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 <new-branch>" 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 <new-branch> to <start-point>, even if <new-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 <new-branch> [<start-point>]', even with 
> '-f',
> +refuses to change an existing branch `<new-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 <new-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,8 +300,8 @@ 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>::
> -	The name of the branch to create or delete.
> +<new-branch>::
> +	The name of the branch to create.
>  	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.
> @@ -311,14 +311,10 @@ 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>::
> +<branch>::
>  	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

Re: [PATCH] branch: adjust documentation

[Dragan Simic]

Hello Junio,

On 2024-02-20 21:34, Dragan Simic wrote:
> On 2024-02-20 21:25, Rubén Justo wrote:
>> Adjust the placeholders 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>
> 
> Looking good to me!

Just checking, do you see the changes that Ruben proposed in this patch
fit for our starting point in the git-branch documentation rewrite?

> Reviewed-by: Dragan Simic <dsimic@manjaro.org>
> 
>> ---
>> 
>>  Documentation/git-branch.txt | 54 
>> +++++++++++++++++-------------------
>>  1 file changed, 25 insertions(+), 29 deletions(-)
>> 
>> diff --git a/Documentation/git-branch.txt 
>> b/Documentation/git-branch.txt
>> index 0b08442932..489507e25f 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 
>> <new-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 <new-branch>" 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 <new-branch> to <start-point>, even if <new-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 <new-branch> [<start-point>]', even with 
>> '-f',
>> +refuses to change an existing branch `<new-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 <new-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,8 +300,8 @@ 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>::
>> -	The name of the branch to create or delete.
>> +<new-branch>::
>> +	The name of the branch to create.
>>  	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.
>> @@ -311,14 +311,10 @@ 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>::
>> +<branch>::
>>  	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

Re: [PATCH] branch: adjust documentation

[Junio C Hamano]

Dragan Simic <dsimic@manjaro.org> writes:

> Hello Junio,
>
> Just checking, do you see the changes that Ruben proposed in this patch
> fit for our starting point in the git-branch documentation rewrite?

The synopsis part may, but with reservations.  I know you two are
aiming to make this in many small incremental steps, but even then
I'd have to say the way these placeholder words will be used in the
text part (both DESCRIPTION and OPTIONS) will be so different from
the final shape envisioned [*1*], the wording that may fit well within
the current text might not be the best fit in the final text.

The current description section talks about option and its arguments
without showing the syntax, making it unnecessary to be extra
verbose.  For example, we see something like this:

    With a `-m` or `-M` option, <oldbranch> will be renamed to
    <newbranch>.  If <oldbranch> had a corresponding reflog, it is
    renamed to match ...

But in the final shape of the documentation, I would like to see the
description section not talk about these arguments, and would read
more like

    When given `-m` or `-M` options, the command renames an existing
    branch to a different name.

among short descriptions made at the conceptual level on other modes
like "listing" mode, "delete" mode, etc. [*3*] 

And the option description would become something like [*]:

    -m [<one>] <two>::
	Renames the branch <one> (the current branch is used when
	not given) to a new name <two>, together with its reflog and
	configuration settings for the branch. ...

    Side note: <one> and <two> are meta-placeholders for the purpose
    of this document; Ruben's patch proposes to call them <branch>
    and <new-branch>.

Now in such a context, <one> and <two> placeholders having actually
the word "branch" in it would sound redundant and awkward to read,
Even though the choice of words Ruben made in the patch under
discussion may work well in the current document structure.  I
suspect these words will have to be chosen again when we start
making the real organizational changes to the description and
options sections.

In other words, I do not think that the patch makes an effective
"one good step in the right direction".  At least, I couldn't see
how the wording for placeholders the patch proposes to use would be
helpful in deciding the placeholders used in the final version.

Thanks for pinging.


[Footnotes]

 *1* Do we share the vision on how the final version should look
     like?  Here I am assuming "the final shape envisioned" is along
     the lines of [*2*], i.e.

     (1) trim descriptions to just enumerate different modes of
         operations with explanation on what they do at the
         conceptual level;

     (2) make each entry in the options section self contained, by
         showing the option with their <argument>s, referring to
         them in the explanation text;

     (3) remove non-option <argument> from the options list.

 *2* https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/

 *3* Because "git branch" does so many things, the DESCRIPTION
     section should first say the purpose of the section is to serve
     as brief catalog of features to help readers to find the entry
     in the option section to jump to quickly.  Something like:

     The "git branch" command works in many modes (see SYNOPSIS
     above).  By default the command works in the "list" option (the
     `--list` option explicitly asks for this mode).

     will be at the beginning of the section.  The first four
     paragraphs in the current DESCRIPTION section is about this
     list mode.  The first three of them should probably be moved to
     the OPTIONS section under `--list`.  The fourth paragraph
     should be split and described in the entries of individual
     options it talks about in the OPTIONS section.
.

Re: [PATCH] branch: adjust documentation

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> The current description section talks about option and its arguments
> without showing the syntax, making it unnecessary to be extra
> verbose.  For example, we see something like this:

"unnecessarily extra verbose" is what I meant to say.

Re: [PATCH] branch: adjust documentation

[Dragan Simic]

On 2024-02-28 18:20, Junio C Hamano wrote:
> Dragan Simic <dsimic@manjaro.org> writes:
>> Just checking, do you see the changes that Ruben proposed in this 
>> patch
>> fit for our starting point in the git-branch documentation rewrite?

First of all, I _really_ appreciate your highly detailed feedback.
Thank you very much for taking the time to write it all down!

> The synopsis part may, but with reservations.  I know you two are
> aiming to make this in many small incremental steps, but even then
> I'd have to say the way these placeholder words will be used in the
> text part (both DESCRIPTION and OPTIONS) will be so different from
> the final shape envisioned [*1*], the wording that may fit well within
> the current text might not be the best fit in the final text.

Please, let me remind you that I've already agreed upon doing it all
in one fell swoop, which may consist of multiple patches in a series,
but applied as a whole.

> The current description section talks about option and its arguments
> without showing the syntax, making it unnecessary to be extra
> verbose.  For example, we see something like this:
> 
>     With a `-m` or `-M` option, <oldbranch> will be renamed to
>     <newbranch>.  If <oldbranch> had a corresponding reflog, it is
>     renamed to match ...
> 
> But in the final shape of the documentation, I would like to see the
> description section not talk about these arguments, and would read
> more like
> 
>     When given `-m` or `-M` options, the command renames an existing
>     branch to a different name.
> 
> among short descriptions made at the conceptual level on other modes
> like "listing" mode, "delete" mode, etc. [*3*]

I agree on that being the final outcome, because the descriptions
of arguments actually belong to the envisioned "OPTIONS" section,
as part of the command descriptions.

> And the option description would become something like [*]:
> 
>     -m [<one>] <two>::
> 	Renames the branch <one> (the current branch is used when
> 	not given) to a new name <two>, together with its reflog and
> 	configuration settings for the branch. ...
> 
>     Side note: <one> and <two> are meta-placeholders for the purpose
>     of this document; Ruben's patch proposes to call them <branch>
>     and <new-branch>.
> 
> Now in such a context, <one> and <two> placeholders having actually
> the word "branch" in it would sound redundant and awkward to read,
> Even though the choice of words Ruben made in the patch under
> discussion may work well in the current document structure.  I
> suspect these words will have to be chosen again when we start
> making the real organizational changes to the description and
> options sections.

Well, perhaps it's the best to revisit the argument naming later.

> In other words, I do not think that the patch makes an effective
> "one good step in the right direction".  At least, I couldn't see
> how the wording for placeholders the patch proposes to use would be
> helpful in deciding the placeholders used in the final version.

I see, thanks for the clarification.

> [Footnotes]
> 
>  *1* Do we share the vision on how the final version should look
>      like?  Here I am assuming "the final shape envisioned" is along
>      the lines of [*2*], i.e.
> 
>      (1) trim descriptions to just enumerate different modes of
>          operations with explanation on what they do at the
>          conceptual level;

Yes, that's also how I see it.  The "DESCRIPTION" sections should
end up describing only the available different modes.

>      (2) make each entry in the options section self contained, by
>          showing the option with their <argument>s, referring to
>          them in the explanation text;

Agreed once again.  The "OPTIONS" section should end up describing
the available options, together with their respective arguments, in
a way that doesn't require the reader to jump to other places in the
document to fully understand each of the options.

>      (3) remove non-option <argument> from the options list.

Yes, that goes along with the descriptions being self-contained.

>  *2* https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/

Sure, I already went through your message linked above, which already
described it quite well.

>  *3* Because "git branch" does so many things, the DESCRIPTION
>      section should first say the purpose of the section is to serve
>      as brief catalog of features to help readers to find the entry
>      in the option section to jump to quickly.  Something like:

Yup, as I already explained it above.  To reiterate, the purpose of
the "DESCRIPTION" section is to let the reader know what git-branch
can do, in form of easily readable prose.

>      The "git branch" command works in many modes (see SYNOPSIS
>      above).  By default the command works in the "list" option (the
>      `--list` option explicitly asks for this mode).
> 
>      will be at the beginning of the section.  The first four
>      paragraphs in the current DESCRIPTION section is about this
>      list mode.  The first three of them should probably be moved to
>      the OPTIONS section under `--list`.  The fourth paragraph
>      should be split and described in the entries of individual
>      options it talks about in the OPTIONS section.

Agreed, once again. :)  Most of the prose currently found in the
"DESCRIPTION" section should actually be moved to the various command
descriptions in the envisioned future "OPTIONS" section.

Re: [PATCH] branch: adjust documentation

[Rubén Justo]

On Wed, Feb 28, 2024 at 09:20:02 -0800, Junio C Hamano wrote:

> The current description section talks about option and its arguments
> without showing the syntax, making it unnecessarily extra verbose.
> For example, we see something like this:
> 
>     With a `-m` or `-M` option, <oldbranch> will be renamed to
>     <newbranch>.  If <oldbranch> had a corresponding reflog, it is
>     renamed to match ...
> 
> But in the final shape of the documentation, I would like to see the
> description section not talk about these arguments, and would read
> more like
> 
>     When given `-m` or `-M` options, the command renames an existing
>     branch to a different name.
> 

Good.

> among short descriptions made at the conceptual level on other modes
> like "listing" mode, "delete" mode, etc. [*3*] 
> 
> And the option description would become something like [*]:
> 
>     -m [<one>] <two>::
> 	Renames the branch <one> (the current branch is used when
> 	not given) to a new name <two>, together with its reflog and
> 	configuration settings for the branch. ...

> Now in such a context, <one> and <two> placeholders having actually
> the word "branch" in it would sound redundant and awkward to read,

Indeed.

But I'm on the fence.  Do we have to use "Renames the branch <one>"?

If we wisely choose the placeholder, perhaps we can write:

    -m [<one>] <two>::
	Renames <one> (the current branch is used when not given) to
	a new name <two>, together with its reflog and configuration
	settings ...

And if <one> is _good enough_ then "current branch is used when ..."
should seem somewhat redundant.  So it could be possible to end up
having something like:

    -m [<one>] <two>::
	Renames <one> to a new name <two>, together with its reflog
	and configuration settings ...

Are we going to say "the current branch is used when ..." in the
description for the other options too?  The description for "-c|-C",
"--edit-description", "--unset-upstream", ...  Perhaps we are, and it
will sound repetitive.  However, even if we do, with the _good enough_
placeholder the user will be able to fill the gaps we might leave in
the documentation, like the one that presumably has bring us here:
pull.1613.git.git.1701303891791.gitgitgadget@gmail.com.

And finally;  Can't <one> and <two> be consistent with other bits we
have in the documentation like the descriptions of "git switch <one>",
"git checkout -b <two>" or "git init -b <three>"?

After the revamp, I'll be less happy (but happy :-) nonetheless) if we
end up having a SYNOPSIS similar to the one we have today:

 - Documentation/git-branch.txt:
      'git branch' (-c | -C) [<one>] <two>
      'git branch' (-d | -D) [-r] <three>...
      'git branch' --edit-description [<three>]

It seems to me to be made up of disconnected pieces.

And for reference:

 - Documentation/git-switch.txt:
      'git switch' [<options>] [--no-guess] <four>
      'git switch' [<options>] --orphan <five>

 - Documentation/git-init.txt:
      'git init' [--initial-branch=<six>]

My apologies if I'm pushing too hard on this and being reiterative in
my messages in this series.  My intention has been to explore the use
we want of the placeholders.  Of course, this is not at odds with my
sympathy for the vision proposed.  I agree on the direction.

> Even though the choice of words Rubén made in the patch under
> discussion may work well in the current document structure.

My patch is mainly about CodingGuideLines:

	If a placeholder has multiple words, they are separated by dashes:
	  <new-branch-name>
	  --template=<template-directory>

Re: [PATCH] branch: adjust documentation

[Junio C Hamano]

Rubén Justo <rjusto@gmail.com> writes:

> If we wisely choose the placeholder, perhaps we can write:
>
>     -m [<one>] <two>::
> 	Renames <one> (the current branch is used when not given) to
> 	a new name <two>, together with its reflog and configuration
> 	settings ...
>
> And if <one> is _good enough_ then "current branch is used when ..."
> should seem somewhat redundant.  So it could be possible to end up
> having something like:
>
>     -m [<one>] <two>::
> 	Renames <one> to a new name <two>, together with its reflog
> 	and configuration settings ...

If you use <the-current-branch-or-a-named-branch> or something
awkward like that as <one>, surely you can.  But I do not think we
want to go there.  And neither <branch-name> or <old-branch> would
remove the need for "if omitted then the current branch is used", I
am afraid, even though there may be a way to rephrase it more
concisely, e.g. "Rename the current branch (or <one> when given)..."

> Are we going to say "the current branch is used when ..." in the
> description for the other options too?  The description for "-c|-C",
> "--edit-description", "--unset-upstream", ...  Perhaps we are, and it
> will sound repetitive.

Do not forget that the objective of the larger-picture-revamping of
this page is to make the description of each option self-contained.
Similarity between -m's description and -c's description does not
count as being uselessly repetitive.

>> Even though the choice of words Rubén made in the patch under
>> discussion may work well in the current document structure.
>
> My patch is mainly about CodingGuideLines:
>
> 	If a placeholder has multiple words, they are separated by dashes:
> 	  <new-branch-name>
> 	  --template=<template-directory>

Yes, and that will be something we want to address _after_ we pick
what word or phrase would replace <one> or <two> in the above at the
conceptual level.  If we picked a single word, say "branch", we do
not even need to worry about dashes, and spell it just <branch>.  If
we did not pick "old branch", then we'd use "<old-branch>", but doing
such a conversion based on the current text is a wasted work, if we
end up using say "original branch" as the phrase, for example.

So if your patch is mainly about that part of the guideline, it is
addressing the documentation update in a wrong order, creating
possibly a wasted work.

Re: [PATCH] branch: adjust documentation

[Rubén Justo]

On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:

> Do not forget that the objective of the larger-picture-revamping of
> this page is to make the description of each option self-contained.
> Similarity between -m's description and -c's description does not
> count as being uselessly repetitive.

OK.  I was not considering this.

Thanks.

Re: [PATCH] branch: adjust documentation

[Dragan Simic]

On 2024-02-29 21:02, Rubén Justo wrote:
> On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:
> 
>> Do not forget that the objective of the larger-picture-revamping of
>> this page is to make the description of each option self-contained.
>> Similarity between -m's description and -c's description does not
>> count as being uselessly repetitive.
> 
> OK.  I was not considering this.

I'd also like to avoid repetition, but if we want to have self-contained
command descriptions (which is good), some repetition is unavoidable.
In fact, we can see what avoiding the repetition has lead us to in the
current state of the git-branch(1) man page.

Re: [PATCH] branch: adjust documentation

[Rubén Justo]

On Thu, Feb 29, 2024 at 09:09:25PM +0100, Dragan Simic wrote:
> On 2024-02-29 21:02, Rubén Justo wrote:
> > On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:
> > 
> > > Do not forget that the objective of the larger-picture-revamping of
> > > this page is to make the description of each option self-contained.
> > > Similarity between -m's description and -c's description does not
> > > count as being uselessly repetitive.
> > 
> > OK.  I was not considering this.
> 
> I'd also like to avoid repetition, but if we want to have self-contained
> command descriptions (which is good), some repetition is unavoidable.

I don't see much of a problem with repetitions.  Within the
self-containmnent aspect it makes a lot of sense.  And, after all, my
messages have been mainly about repeating ... placeholders.

> In fact, we can see what avoiding the repetition has lead us to in the
> current state of the git-branch(1) man page.

Indeed.  I agree that the lack of repetition has brought us here.  But I
think we're not 100% aligned in what repetition is :-), yet.  We're
working on it!

Thanks.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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.

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Rubén Justo]

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!

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Kyle Lippincott]

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
>

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Kyle Lippincott]

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

Re: [PATCH] branch: rework the descriptions of rename and copy operations

[Dragan Simic]

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