From: Jacob Abel <jacobabel@nullpo.dev>
Date: Tue, 20 Dec 2022 23:24:29 GMT
Subject: Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
Message-ID: <20221220232417.v3tvugyav36m32ry@phi>
In-Reply-To: <xmqqo7ryyc4f.fsf@gitster.g>

On 22/12/20 12:42PM, Junio C Hamano wrote:
> Jacob Abel <jacobabel@nullpo.dev> writes:
>
> > Subject: Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
>
> s/Include/include/;

Done.

>
> > 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 ...

Done.

>
> >  '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.

>
> > 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.

Done.