Documentation
¶
Overview ¶
Package build exposes compile-time build metadata: version, commit, branch, build time, and platform information.
Values are provided in one of two ways, in order of precedence:
- ldflags at link time, e.g. go build -ldflags "-X github.com/jordanbrauer/hex/build.version=v1.2.3 \ -X github.com/jordanbrauer/hex/build.commit=abcdef \ -X github.com/jordanbrauer/hex/build.date=2026-01-02T03:04:05Z"
- debug.ReadBuildInfo, which the Go toolchain populates automatically for module-aware builds (`go build` inside a git repo, `go install`, etc.). This is how we get a real commit and build time without requiring the caller to pass ldflags.
When neither source has a value the accessors return safe placeholders ("dev", "HEAD") and Debug() reports true.
This package intentionally performs no I/O beyond reading debug.BuildInfo once at import time. Nothing shells out to git. Nothing panics.
Index ¶
Constants ¶
const ( UnknownVersion = "dev" UnknownCommit = "HEAD" UnknownBranch = "HEAD" )
The placeholder values used when nothing else is known. Exported so tests (and consumers who want to detect the "unknown" state) can compare against them without repeating string literals.
Variables ¶
This section is empty.
Functions ¶
func Branch ¶
func Branch() string
Branch returns the source branch. Only populated via ldflags; debug.BuildInfo does not expose branch information. Returns "HEAD" if unset.
func Commit ¶
func Commit() string
Commit returns the full commit SHA. Sourced from -ldflags "-X ...commit" first, then debug.BuildInfo (vcs.revision), then "HEAD".
func Debug ¶
func Debug() bool
Debug reports whether this is an unversioned / development build. True when neither ldflags nor debug.BuildInfo produced a real version or commit.
func GoVersion ¶
func GoVersion() string
GoVersion returns the Go toolchain version the binary was compiled with, stripped of the leading "go" (e.g. "1.26.4" not "go1.26.4").
func Info ¶
func Info() string
Info returns a multi-line human-readable summary of the build metadata. Suitable as the body of a `version` CLI subcommand.
func Modified ¶
func Modified() bool
Modified reports whether the working tree had uncommitted changes at build time, according to debug.BuildInfo. False for ldflags-only builds.
func ShortCommit ¶
func ShortCommit() string
ShortCommit returns the first 7 characters of Commit, or Commit itself if it is shorter than 7 characters (e.g. the "HEAD" placeholder).
Types ¶
This section is empty.
Source Files