Re: [PATCH 2/2] git-worktree.txt: add missing `-v` to synopsis for `worktree list`

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Dec 6, 2021, 13:34 UTC
Message-ID: <CAPig+cQ82UC3MRSswGtnCcB13wdhTNYzDex=tFSuFwFCjL3ErA@mail.gmail.com>
In-Reply-To: <xmqqa6hfmn3u.fsf@gitster.g>

On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano <gitster@pobox.com> wrote:

Show 21 quoted lines

> Eric Sunshine <sunshine@sunshineco.com> writes:
> > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
> >> Aside: I've been thinking of hacking something up to just change all
> >> these "[verse]" bits in the *.txt source to:
> >>
> >>     [verse]
> >>     $(git worktree -h)
> >>
> >> And then have the doc build process pick that up, run 'git $name -h', do
> >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the
> >> docs like that.
> >
> > One caution that springs to mind is that there may be external tooling
> > which processes these documentation files directly, and such a change
> > might break them. (The one which popped to mind immediately was the
> > git-scm.{org,com} website, though I don't know what their tooling
> > looks like.)
>
> Also it would slow us down by making the .txt variant we see in the
> source tree harder to read (or in this case, impossible to see without
> building the documentation).

Taking this point into consideration, a middle-ground alternative to Ævar's idea would be to add tooling which only compares (by some definition of "compare") the output of `git blah -h` with the synopsis in `git-blah.txt` and complains if there are significant differences (by some definition "significant" and "difference"). It doesn't automate-away the work of keeping the synopsis up-to-date, but at least would flag inconsistencies.