| Message ID | 96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | branch: adjust documentation | expand |
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
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
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 <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.
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.
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>
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.
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.
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.
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 --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
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(-)