19.8.1 Setting the package version

When the maintainer has decided about the version number for the next build (and likely also the next tarball), they implement that decision by storing this version number in a file named .tarball-version at the top level of the package. This is a simple one-line text file.

The maintainer can, alternatively, decide to let the git version be the version number. To implement this choice, they remove the file .tarball-version at the top level of the package.

The actual version number comes from an invocation of the program git-version-gen, part of the Gnulib module git-version-gen. It looks at the file .tarball-version, if that exists, and at the current checkout, otherwise.

The file .tarball-version should not be put under version control. Therefore you may want to list it in the package’s top-level .gitignore file.

But you need a Makefile.am rule that will make sure that .tarball-version will exist in distribution tarballs:

dist-hook: dist-tarball-version
.PHONY: dist-tarball-version
dist-tarball-version:
	echo '$(VERSION)' > $(distdir)/.tarball-version

Typically, the maintainer will set the version number in a clean directory (i.e. after “make distclean”). In order to adapt to alternative workflows, the file GNUmakefile, part of the Gnulib module gnumakefile, contains a rule that will print a warning or possibly call autoreconf if it finds that the version has changed but has not yet been propagated. Reminder: Not every package supports autoreconf.