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

From: Jeff King <peff@peff.net>
Date: Dec 3, 2021, 15:52 UTC
Message-ID: <Yao9NwxQ91XO8k1G@coredump.intra.peff.net>
In-Reply-To: <211203.865ys5soqk.gmgdl@evledraar.gmail.com>

On Fri, Dec 03, 2021 at 03:57:41PM +0100, Ævar Arnfjörð Bjarmason wrote:

Show 11 quoted lines

> > 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.)
> 
> True, I hadn't looked into how that worked before, but behold!
> https://github.com/git/git-scm.com/blob/main/lib/tasks/index.rake
> 
> It seems to be a re-implementation of a non-trivial part of the doc
> building process.

Yeah. It's kind of ugly, but the complication there is that the docs are updated on a running heroku dyno which does not actually have a clone of the new version of Git, let alone an actual build.

It's also hard for it to just use the output of our "make" anyway, since there's some munging that happens to fit the page content inside the rest of the site, changing links, etc. We could in theory operate on the result of "make html" more directly, but it would definitely require some changes.

IMHO the way the site operates now (with "live" updates by extracting content from git.git and shoving it into a database) is not ideal. It's not like we're importing new Git versions once per minute. It would be easier to reason about as a "static site" which is built by a process which actually has a clone of git.git and invokes "make html" there, post-processes the pages, and saves the whole thing as a Git tree. And then run that build occasionally (at new releases, or changes to the source, but also periodically via GitHub Actions or similar to pick up changed book content). It's just a big enough change (and there are some gotcha around things like site search) that I've never gotten around to it.

-Peff