From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 20 Dec 2022 03:42:24 GMT
Subject: Re: [PATCH v5 1/4] worktree add: Include -B in usage docs
Message-ID: <xmqqo7ryyc4f.fsf@gitster.g>
In-Reply-To: <20221220023637.29042-2-jacobabel@nullpo.dev>

Jacob Abel <jacobabel@nullpo.dev> 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.