3 ways to embed a commit hash in Go programs

Whether you are using Go to write a simple console-based utility or a fancy web application, it is always helpful to reference the previous version of your software. This information is essential, especially for developers. They need to know what the source code looked like in previous versions, so they can debug any issues introduced at specific points in time.

To do that, you need a system that can control and manage different versions of the source code, such as git. Whenever you want to capture a snapshot of the program's current codebase, you run a git commit command that saves the code at that point in time. To make sure you do not overwrite a previously saved record, git creates (by default) a unique identifier, hashed with the SHA-1 algorithm, for every commit.

Usually, when a decent amount of progress has been made, a couple of features have been implemented and lots of bugs have been fixed, it's about time to make things official and announce a new release version of your software. Of course, embedding the release version is not new. You most likely already have automation in place to provide this information within your software (e.g., during the release pipeline). But this kind of progress doesn't happen in a day. So what happens in the meantime? You do what the rolling-release model does, associating every build (go build) with a snapshot of the code at that point in time. This is when the git commit hash comes in handy. There are three ways to embed this hash into your Go program.

1. Using -ldflags

The most common way is by using a string variable, a value populated at build time via flags.

For example:

var Commit string

go build -ldflags="-X main.Commit=$(git rev-parse HEAD)"

The disadvantage here is that you need to remember this syntax and run it every time you build your code. You can make this easier by using Makefiles to do that for you.

2. Using go generate

Another way is to use a file (let's call it VERSION.txt). This process requires the installation of Go 1.16 or later, since it uses go:generate to populate the file contents and go:embed to populate the variable. For example:

//go:generate sh -c "printf %s $(git rev-parse HEAD) > VERSION.txt"
//go:embed VERSION.txt
var Commit string

You have to remember to run go generate every time before go build. To avoid developing an unnecessary memory muscle, you can put this block into your Makefile, which is part of the @build target.

With this method, you have a file (VERSION.txt) that always captures the latest commit hash of the repository. While this information is not that useful information for you (since you can also see this information in GitHub's user interface or just using git), the advantage here is that you can use this file for other things in your CI/CD environment as well. If a component needs to know the version, now it has an easy way to find it: by reading this file.

However, the downside here is that you have to remember to include that file as part of your code well. This is something that is generated by the computer and not written by a person, so it's not uncommon for people to forget about it.

This way is mostly preferred when you are officially releasing a new stable version of your software, but not every time your merge a PR. Although I can see the benefits, I wouldn't recommend this for daily use.

3. Using runtime/debug package

The third solution to this problem is quite simple and comes fresh from the runtime/debug package, which is already part of the official Go library.

import "runtime/debug"

var Commit = func() string {
  if info, ok := debug.ReadBuildInfo(); ok {
    for _, setting := range info.Settings {
      if setting.Key == "vcs.revision" {
        return setting.Value
      }
    }
  }

  return "" 
}()

Apart from vsc.revision, you can also query for vcs.time (that is the timestamp of the commit message) and check vcs.modified (that is true if the binary builds from uncommitted changes). To make this work, you need Go 1.18, and should build using the -buildvcs (which should be available in your goenv).

This is a great way to include the commit hash information without having to take care of building with a specific set of ldflags or running go generate every single time. As long as you have Go 1.18 or higher, a simple go build should suffice to pass the git information into the Commit string variable.

What's the best way to embed a commit hash?

You might ask: Which of the three ways is the best? The answer is that you should pick the one that fits your needs. You might not need any of these methods, or you might use more than one in combination.

Personally, I like the last way, because I don't need a Makefile and I don't want to remember to do anything extra out of the ordinary. So, if the usual go build gives me all I need, then that's enough for me. Less is more!