Build Flags and Version Stamping

A build flag is an option you give to go build. It changes the binary that comes out without changing a line of source. Two flags matter when you ship: -ldflags and -trimpath.

Stamping a version

-ldflags passes arguments to the linker, the tool that assembles the final executable. The useful linker argument is -X importpath.name=value, documented as: set the value of the string variable in importpath named name to value. The documentation is strict about when it works: only if the variable is declared uninitialised, or initialised to a constant string expression. So var version = "dev" can be stamped. A version assembled by a function call at startup cannot. -s omits the symbol table and debug information and -w omits the DWARF symbol table, which makes the file smaller and stack traces less useful. -ldflags "..." and -ldflags="..." are the same thing written two ways.

Reproducible builds

-trimpath removes all file system paths from the resulting executable. Without it the binary carries absolute paths from the machine that built it, including your home directory. With it, recorded file names begin with a module path and version instead, so two people building the same commit get the same bytes.

You may not need -X for the commit

Since Go 1.18 the go command stamps version control details on its own: vcs.revision, vcs.time and vcs.modified. The -buildvcs flag controls it and defaults to auto, which stamps when the main package, its module and the current directory are in the same repository. Read them at runtime with debug.ReadBuildInfo, or from outside with go version -m bin/app. Keep -X for what the repository does not know, such as a release tag.

package main

import "fmt"

// version and commit are replaced at link time by:
//
//	go build -ldflags "-X main.version=1.4.0 -X main.commit=9f2c1ab" .
//
// Both must stay plain string variables holding a constant, or -X is ignored
// and these defaults survive into the shipped binary.
var (
	version = "dev"
	commit  = "none"
)

func main() {
	fmt.Printf("app %s (commit %s)\n", version, commit)
}

// Built with a plain `go build .`, with no -ldflags at all:
//
// Output:
// app dev (commit none)

package main

import (
	"fmt"
	"runtime/debug"
)

// buildRevision returns the commit go build recorded, or "unknown".
func buildRevision() string {
	info, ok := debug.ReadBuildInfo()
	if !ok {
		return "unknown"
	}
	for _, s := range info.Settings {
		if s.Key == "vcs.revision" {
			return s.Value
		}
	}
	return "unknown"
}

func main() {
	fmt.Println("revision:", buildRevision())
}

go build -trimpath \
	-ldflags "-s -w -X main.version=1.4.0 -X main.commit=$(git rev-parse --short HEAD)" \
	-o bin/app ./cmd/app

# Print the module, dependency versions and build settings inside the binary.
go version -m bin/app

# And what the program itself reports.
./bin/app
# app 1.4.0 (commit 9f2c1ab)

// Package build holds values the linker fills in.
package build

// Version is set with:
//
//	-ldflags "-X example.com/app/internal/build.Version=1.4.0"
//
// The name before the dot is the package's full import path, not its short name.
var Version = "dev"

// Short returns the version without a leading "v", for display.
func Short() string {
	if len(Version) > 1 && Version[0] == 'v' {
		return Version[1:]
	}
	return Version
}