make GIT_VERSION=foo broken, was Re: [PATCH v2] doc: remove extra quotes in generated docs

From: Jeff King <peff@peff.net>
Date: Dec 18, 2024, 11:33 UTC
Message-ID: <20241218113324.GA594795@coredump.intra.peff.net>
In-Reply-To: <xmqqbjx9yedb.fsf@gitster.g>

On Tue, Dec 17, 2024 at 05:22:08PM -0800, Junio C Hamano wrote:

Show 15 quoted lines

> > -<refmiscinfo class="source">Git 2.47.1.409.g9bb10d27e7</refmiscinfo>
> > -<refmiscinfo class="manual">Git Manual</refmiscinfo>
> > +<refmiscinfo class="source">'Git 2.47.1.410.ga38edab7c8'</refmiscinfo>^M
> > +<refmiscinfo class="manual">'Git Manual'</refmiscinfo>^M
> >  </refmeta>
> >  <refnamediv>
> >      <refname>git-bisect</refname>
> > ```
> 
> Thanks for filling the blanks in ;-)
> 
> The above differences however seem to be absorbed before these
> strings reach git-bisect.1 by the documentation toolchain;
> Running Documentation/doc-diff with --asciidoc or --asciidoctor
> options do not show the difference in single quotes.

Hmm. I thought that might be because we override the version and date strings in doc-diff to prevent extra output. But it seems that was broken by the same commit. Try:

  ./doc-diff a38edab7^ a38edab7

and you'll get a bunch of:

-Git omitted 1970-01-01 GIT-ADD(1) +Git 2.47.1.410.ga 2024-12-06 GIT-ADD(1)

diffs which show the breakage starting (and after that, you get further changes as each version changes by one commit).

The override is done by setting GIT_VERSION on the make command line. And indeed, it seems like:

  make GIT_VERSION=foobar

no longer has any effect. That could be a problem for packagers, as well, if they try to inject a custom version string (e.g., to represent the upstream version plus their patches). I don't know if anybody does that, though.

The root of the problem is that we used to generate GIT-VERSION-FILE and source it as a Makefile snippet. That let the usual Makefile precedence rules override what was in the file. But after that commit, we use the script to directly generate the version _and_ replace the contents of asciidoc.conf, etc.

I think the workaround here would be to manually override asciidoc's config like this:

  make ASCIIDOC='asciidoc -amansource="Git omitted" -arevdate=1970-01-01'

But besides being horrible, I think that only works because asciidoc gives us a layer of indirection. The same problem exists for the built-in version-def.h. Try this:

  $ git checkout v2.47.0
  $ make GIT_VERSION=super-secret
  [...]
  $ bin-wrappers/git version
  git version super-secret

  $ git checkout v2.48.0-rc0
  $ make GIT_VERSION=super-secret
  [...]
  $ bin-wrappers/git version
  git version 2.48.0.rc0

I wondered if this would also leak out over the network via the agent string, but it doesn't seem to. I think because GIT_USER_AGENT is handled specially in the script; we accept the value from the environment and only default it to git/$GIT_VERSION.

Perhaps the script should be doing the same for GIT_VERSION itself, along with GIT_DATE?

-Peff