PSA using Git tags as library version in Hex packages

For some time I had big problem with Mix that it didn’t supported fetching project version from Git, like Rebar3 does with {version, git} in .app.src. So finally I have crafted the snippet that works and does exactly that:

defp version do
  case :file.consult('hex_metadata.config') do
    {:ok, data} ->
      {"version", version} = List.keyfind(data, "version", 0)
    _ ->
      version =
        case System.cmd("git", ~w[describe --dirty=+dirty]) do
          {version, 0} ->

          {_, code} ->
  "Git exited with code #{code}, falling back to 0.0.0")


      case Version.parse(version) do
        {:ok, %Version{pre: ["pre" <> _ | _]} = version} ->

        {:ok, %Version{pre: []} = version} ->

        {:ok, %Version{patch: patch, pre: pre} = version} ->
          to_string(%{version | patch: patch + 1, pre: ["dev" | pre]})

        :error ->
"Failed to parse #{version}, falling back to 0.0.0")


And now use [version: version()] and it will automatically use version from Hex when available, Git version when project is fetched via Git, if everything fails then it will fall back to 0.0.0.

Unfortunately as Mix do not have a way to have per-project extensions preloaded it need to be distributed as such snippet and I cannot make it into library that would make it clearer.

I have used above in Watermelon and I have tested that it works as expected.


Do you have an example of what a git version looks like?

git describe --dirty=+dirty returns:

  • <tag> if current HEAD points to the annotated (or signed) tag
  • <tag>-<num>-g<hash> where <tag> is the newest annotated tag reachable from HEAD, <num> is amount of commits since that tag, and <hash> is hash of current HEAD
  • <version>+dirty where <version> is one of the above, this happens when there are uncommitted changes in current work tree

Rest of the code does that:

  • If there is hex_metadata.config file (which is always there for libs fetched from the Hex) it will use version from there
  • If project is fetched from Git then it will try to use git describe --dirty=+dirty
  • If version returned by Git contains pre version tag that starts with pre then it will leave it as is
  • If version returned by Git do not contain pre version tag (so we are directly on signed tag) then we leave version as is
  • If above didn’t match, then we bump patch version by one and add dev pre tag
  • If all of above fails - return version 0.0.0 (probably I should add tag dev there as well)
1 Like