On Thu, Nov 3, 2022 at 9:05 PM Jacob Abel <jacobabel@xxxxxxxxxx> 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@xxxxxxxxxxxxxx/
[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@xxxxxxxxxxxxxx/
> Signed-off-by: Jacob Abel <jacobabel@xxxxxxxxxx>
> ---
> 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>]")
