Jacob Abel <jacobabel@xxxxxxxxxx> writes:
> Subject: Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
s/Include/include/;
> While -B behavior is already documented, it was not included in the
> usage docs for either the man page or the help text.
Good.
> This change fixes
> that and brings the usage docs in line with how the flags are documented
> in other commands such as git checkout.
We often just give an order to the codebase to "be like so", before
describing the effect of following such an order. I.e.
Document "-B" next to where "-b" is already documented, to
bring the usage docs in line with ...
> 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
> - [-b <new-branch>] <path> [<commit-ish>]
> + [[-b | -B] <new-branch>] <path> [<commit-ish>]
This is wrong, I think. We want
[(-b | -B) <new-branch>] <path> [<commit-ish>]
instead.
[ a-thing ] means "a-thing can exist here, and it does not have to".
[ a-thing | another-thing ] means "a-thing or another-thing can
exist here, but neither has to be here". [[-b | -B] <new-branch>]
would allow <new-branch> without either -b or -B, which is not what
we want.
> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index 4a24d53be1..fccb17f070 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -17,7 +17,7 @@
>
> #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>]")
Likewise.
