buildversion

README

Build Version

🏗️ Library for determining and overriding the version of a Go application

Motivations

There are currently a number of ways to distribute a Go application. A user could download a prebuilt release binary, or run go install, or even clone the repo and go build/go run the code directly.

Information such as version strings, git commit SHAs, and timestamps may be available to programs executed in each of these scenarios.

This library aims to surface this information for inclusion in bug reports, or when displaying help text.

Usage

Basic Example

Here is a simple program which templates out the default version, revision, & timestamp properties.

package main

import (
	"fmt"

	"github.com/joshdk/buildversion"
)

func main() {
	tpl := `{{ .Version }}
	{{- if .Revision }} ({{ .Revision }}){{ end }}
	{{- if .Timestamp }} built on {{ .Timestamp }}{{ end }}`

	fmt.Print(buildversion.Template(tpl))
}

When executed with go install or go build we can observe that the current commit, and the time that commit was originally authored, is printed.

$ go install .

$ demo
v0.0.1-0.20250707135443-82e199f920b9 (82e199f) built on 2025-07-07T13:54:43Z

$ go build .

$ ./demo
v0.0.1-0.20250707135443-82e199f920b9 (82e199f) built on 2025-07-07T13:54:43Z

Commit information is not included when executed via go run, so a default version is printed instead.

$ go run .
development

Overriding the Version by Using ldflags

This program can be enhanced to consume build-time provided version, revision, & timestamp values as custom overrides.

var version, revision, timestamp string

func main() {
	tpl := `{{ .Version }}
	{{- if .Revision }} ({{ .Revision }}){{ end }}
	{{- if .Timestamp }} built on {{ .Timestamp }}{{ end }}`

	buildversion.Override(version, revision, timestamp)
	
	fmt.Print(buildversion.Template(tpl))
}

These values can be provided via -ldflags/-X (see https://pkg.go.dev/cmd/link).

$ go build -buildvcs=false -ldflags "-X 'main.version=$(git describe --tags --always)' -X 'main.revision=$(git rev-parse HEAD)' -X 'main.timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')'" .             

$ ./demo
v1.2.3 (82e199f) built on 2025-07-19T03:16:33Z

Templating

The following properties can be referenced from a Go text/template style template body:

Property	Description
{{ .Path }}	Go import path of the main package being run
{{ .Version }}	Package version string
{{ .Revision }}	Current git commit SHA
{{ .ShortRevision }}	Current git commit SHA, truncated to the first 7 characters
{{ .Timestamp }}	RFC3339 timestamp of the current git commit
{{ .OS }}	Current operating system type (GOOS)
{{ .Arch }}	Current CPU architecture (GOARCH)
{{ .Runtime }}	Go runtime version

The {{ .Version }}, {{ .Revision }}/{{ .ShortRevision }}, & {{ .Timestamp }} are not guaranteed to contain a value if not explicitly overridden.

License

This code is distributed under the MIT License, see LICENSE.txt for more information.

Documentation

Overview

Package buildversion asdf...

Index

• func Override(version, revision, timestamp string) any
• func Template(body string) string

Functions

func Override

func Override(version, revision, timestamp string) any

Override replaces the built-in version and timestamp with custom values. Intended to be used with values from e.g. a release build.

func Template

func Template(body string) string

Template renders the provided gotemplate using the built-in/overridden build data. Not intended to be used with a dynamic template, so the function panics if any error is encountered.