Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
On 22/12/20 12:42PM, Junio C Hamano wrote:
Show 5 quoted lines
> Jacob Abel <jacobabel@nullpo.dev> writes:
>
> > Subject: Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
>
> s/Include/include/;
Show 15 quoted lines
>
> > 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 ...
Show 16 quoted lines
>
> > '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.
Ah yep, my mistake. Changed.
Show 13 quoted lines
>
> > 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.Jacob Abel <jacobabel@nullpo.dev>