diff mbox series

branch: adjust documentation

Message ID 96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com (mailing list archive)
State New, archived
Headers show
Series branch: adjust documentation | expand

Commit Message

Rubén Justo Feb. 20, 2024, 8:25 p.m. UTC
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(-)

Comments

Dragan Simic Feb. 20, 2024, 8:34 p.m. UTC | #1
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
Dragan Simic Feb. 28, 2024, 2:19 a.m. UTC | #2
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
Junio C Hamano Feb. 28, 2024, 5:20 p.m. UTC | #3
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.
.
Junio C Hamano Feb. 28, 2024, 5:24 p.m. UTC | #4
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.
Dragan Simic Feb. 29, 2024, 1:56 a.m. UTC | #5
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.
Rubén Justo Feb. 29, 2024, 6:56 p.m. UTC | #6
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>
Junio C Hamano Feb. 29, 2024, 7:33 p.m. UTC | #7
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.
Rubén Justo Feb. 29, 2024, 8:02 p.m. UTC | #8
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.
Dragan Simic Feb. 29, 2024, 8:09 p.m. UTC | #9
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.
Rubén Justo March 2, 2024, 4:18 p.m. UTC | #10
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.
diff mbox series

Patch

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