dune subst inferred version is totally misleading and wrong

[toots]

We were debugging several user builds of our code base and were faced with a spread of totally confusing versions returned from building from a git checkout.

Turns out that dune subst uses the following command to infer dev versions:

git describe --always --dirty --abbrev=7

But this command produces descriptions that are absolutely misleading. Here's an example:

% git describe --always --dirty --abbrev=7 --debug                                                                                                                   
describe HEAD
No exact match on refs or tags, searching to describe
finished search at 6eba12641e468c435114b2afc8763211f41b168a
 annotated        888 v2.2.0
traversed 889 commits
v2.2.0-888-g748cd0c

This is using a commit that is 889 commits (!!) behind the current main (!) branch to describe it and using the versioned tag, which would have you wrongly assume that this is a build for that version.

Also that g prefix before the commit is really misleading as well.

Lastly, tags are by definition moving pieces in git repo. Typically, a release tag can be force-pushed and etc. They are not very useful to have a reliable version. A commit SHA would be much better.

This command should be tightened to return something closer to the current commit. I would expect that most people simply want the current branch name, if it exist, and/or the commit, something like:

[<branch-name>|<tag name>-]-git@<commit SHA>

At the very least, the command should be updated to:

• Include all tags (some git clones don't have them all locally checked out)
• Limit the number of commit to look for. I'd frankly suggest just one!

This gives:

git describe --always --dirty --abbrev=7 --candidates=1 --tags

[maiste]

Thanks for reporting!
@rgrinberg, @emillon is there any blocker that would prevent this change? I would expect people to set the version when they need to. As a result, I don't see a problem for dune to do the substitution this way when no version is provided?

[MisterDA]

This is a difficult problem. It happens often that tags are not part of the main branch, and that the most recent tag reachable from the last commit is quite old. If I look at ocaml's trunk branch for instance:

$ git describe --long --abbrev=7 | sed 's/\([^-]*-g\)/r\1/;s/-/./g'
4.12.0.alpha1.r11226.gc5cde12

I'd suggest looking at Arch Linux VCS package guidelines for the pkgver function. I think that as long as the string Dune reports contains the commit revision, the tag can be allowed to be a bit unreliable.

Meson suggests using an external script: Cement a version obtained from VCS. It also has a vcs_tag function.
Autoconf has git-version-gen.