Subject: Re: [PATCH] Documentation/Makefile: don't re-build on 'git version' changes

From: Junio C Hamano <[email-masked]>
Date: Mon, 05 Jul 2021 12:38:26 -0700

Ævar Arnfjörð Bjarmason <[email-masked]> writes:

> It's useful e.g. on my Debian system to see that the "next" Debian
> packaged is 2.31.0.291.g576ba9dcdaf in docs & "git version", arguably
> less so for documentation.

If it is arguable, perhaps make an argument that is more convincing?

What I dislike the most is that in the sample scenario where master
and next has the same documentation material to build "git-cat-file.1",
the installed result would be different depending on the order of
building the documentation, with the change being discussed, i.e.

    $ git checkout master && make prefix=$HOME/git-master install-doc
    $ git checkout next && make prefix=$HOME/git-next install-doc

would make "~/git-next/bin/git help cat-file" to claim the
documentation is from the "master" version.  Which is not all that
bad, given that there wasn't anything that changed the documentation
between 'master' and 'next'.  But if you swap the installation
order, "~/git-master/bin/git help cat-file" would say that the
documentation is from a version much newer than 'master', which is
not quite acceptable.

I am OK with the approach you hinted to have an option to _hide_ the
version string in the generated documentation (hence they lose their
dependency on GIT-VERSION-FILE), while keeping the dependency of
version.o on GIT-VERSION-FILE, so that something goes wrong in a
built binary, the developer can still ask "git version" to identify
where the binary came from.

Thanks.