From: Jacob Abel <jacobabel@nullpo.dev>
Date: Fri, 04 Nov 2022 04:24:27 GMT
Subject: Re: [PATCH 1/4] worktree add: Include -B in usage docs
Message-ID: <20221104042422.p5jv4thc27zkiiwr@phi>
In-Reply-To: <CAPig+cQA2b6-WVvSjb5iopFO3hmB1RveEBNCuwAXBVa8sV-6Og@mail.gmail.com>

On 22/11/03 11:05PM, Eric Sunshine wrote:
>
> 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@sunshineco.com/
> [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@mail.gmail.com/
>
> > Signed-off-by: Jacob Abel <jacobabel@nullpo.dev>
> > ---
> > 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>]")

I appreciate the context and yes most of those noise-changes in this patchset
were courtesy of `make style`/`git clang-format`. For v2 I'll clean out the
noise to make it a bit easier to review.