| Message ID | 20221104010242.11555-2-jacobabel@nullpo.dev (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | worktree: Support `--orphan` when creating new worktrees | expand |
On Thu, Nov 3, 2022 at 9:05 PM Jacob Abel <jacobabel@nullpo.dev> wrote: > While -B behavior is already documented, it was not included in the > usage docs for either the man page or the help text. This change fixes > that and brings the usage docs in line with how the flags are documented > in other commands such as git checkout. Thanks. Some historical context... Omission of -B from the synopsis was intentional[1] for the sake of brevity. There was a previous "complaint"[2] about the omission of -B in the synopsis. A response[3] to that message suggested that a patch addressing the shortcoming would probably be welcome, though it appears that the author of [2] never submitted such a patch. Summarizing [3]: Whether or not the omission was actually a good decision is questionable. [...] Of course, that decision does not assist newcomers, so adding "-B" to the synopsis would help the page better stand on its own. Which suggests that this patch is probably a good idea. The patch itself looks fine (though the noise-change in the position of the "\" line-splice seems unwarranted). [1]: https://lore.kernel.org/git/1435969052-540-17-git-send-email-sunshine@sunshineco.com/ [2]: https://lore.kernel.org/git/alpine.LFD.2.21.1711140324580.12112@localhost.localdomain/ [3]: https://lore.kernel.org/git/CAPig+cRc7Yqeys=oPEgPnyR4qT7qKYLbH1ifnp+6F6N+mSzNVA@mail.gmail.com/ > Signed-off-by: Jacob Abel <jacobabel@nullpo.dev> > --- > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > @@ -10,7 +10,7 @@ SYNOPSIS > 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] > - [-b <new-branch>] <path> [<commit-ish>] > + [[-b | -B] <new-branch>] <path> [<commit-ish>] > diff --git a/builtin/worktree.c b/builtin/worktree.c > @@ -15,9 +15,9 @@ > -#define BUILTIN_WORKTREE_ADD_USAGE \ > +#define BUILTIN_WORKTREE_ADD_USAGE \ This is just a noise-change which (IMHO) makes it harder to spot the line-splice. (Presumably this whitespace change was made by an automated formatting tool or by a "too smart" editor?) > N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \ > - " [-b <new-branch>] <path> [<commit-ish>]") > + " [[-b | -B] <new-branch>] <path> [<commit-ish>]")
On 22/11/03 11:05PM, Eric Sunshine wrote: > > Thanks. Some historical context... > > Omission of -B from the synopsis was intentional[1] for the sake of brevity. > > There was a previous "complaint"[2] about the omission of -B in the > synopsis. A response[3] to that message suggested that a patch > addressing the shortcoming would probably be welcome, though it > appears that the author of [2] never submitted such a patch. > Summarizing [3]: > > Whether or not the omission was actually a good decision is > questionable. [...] Of course, that decision does not assist > newcomers, so adding "-B" to the synopsis would help the page > better stand on its own. > > Which suggests that this patch is probably a good idea. > > The patch itself looks fine (though the noise-change in the position > of the "\" line-splice seems unwarranted). > > [1]: https://lore.kernel.org/git/1435969052-540-17-git-send-email-sunshine@sunshineco.com/ > [2]: https://lore.kernel.org/git/alpine.LFD.2.21.1711140324580.12112@localhost.localdomain/ > [3]: https://lore.kernel.org/git/CAPig+cRc7Yqeys=oPEgPnyR4qT7qKYLbH1ifnp+6F6N+mSzNVA@mail.gmail.com/ > > > Signed-off-by: Jacob Abel <jacobabel@nullpo.dev> > > --- > > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > > @@ -10,7 +10,7 @@ SYNOPSIS > > 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] > > - [-b <new-branch>] <path> [<commit-ish>] > > + [[-b | -B] <new-branch>] <path> [<commit-ish>] > > diff --git a/builtin/worktree.c b/builtin/worktree.c > > @@ -15,9 +15,9 @@ > > -#define BUILTIN_WORKTREE_ADD_USAGE \ > > +#define BUILTIN_WORKTREE_ADD_USAGE \ > > This is just a noise-change which (IMHO) makes it harder to spot the > line-splice. (Presumably this whitespace change was made by an > automated formatting tool or by a "too smart" editor?) > > > N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \ > > - " [-b <new-branch>] <path> [<commit-ish>]") > > + " [[-b | -B] <new-branch>] <path> [<commit-ish>]") I appreciate the context and yes most of those noise-changes in this patchset were courtesy of `make style`/`git clang-format`. For v2 I'll clean out the noise to make it a bit easier to review.
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 063d6eeb99..4dd658012b 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] - [-b <new-branch>] <path> [<commit-ish>] + [[-b | -B] <new-branch>] <path> [<commit-ish>] 'git worktree list' [-v | --porcelain [-z]] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> diff --git a/builtin/worktree.c b/builtin/worktree.c index 4a24d53be1..b3373fbbd6 100644 --- a/builtin/worktree.c +++ b/builtin/worktree.c @@ -15,9 +15,9 @@ #include "worktree.h" #include "quote.h" -#define BUILTIN_WORKTREE_ADD_USAGE \ +#define BUILTIN_WORKTREE_ADD_USAGE \ N_("git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]\n" \ - " [-b <new-branch>] <path> [<commit-ish>]") + " [[-b | -B] <new-branch>] <path> [<commit-ish>]") #define BUILTIN_WORKTREE_LIST_USAGE \ N_("git worktree list [-v | --porcelain [-z]]") #define BUILTIN_WORKTREE_LOCK_USAGE \
While -B behavior is already documented, it was not included in the usage docs for either the man page or the help text. This change fixes that and brings the usage docs in line with how the flags are documented in other commands such as git checkout. Signed-off-by: Jacob Abel <jacobabel@nullpo.dev> --- Documentation/git-worktree.txt | 2 +- builtin/worktree.c | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) -- 2.37.4