version

Overview ¶

Package version provides utilities to manage, retrieve, and validate version information of a Go application at runtime, supporting multiple version formats including Semantic Versioning (SemVer) and Calendar Versioning (CalVer).

This package captures key metadata about the application build, including the Git tag, full and short commit hashes, build date, Go runtime version, target platform, and the list of Go modules used in the build. These values can be set at build time via linker flags (-ldflags), or automatically extracted from debug.BuildInfo at runtime when available.

Version Information Sources:

1. Build-time ldflags (recommended for releases):

• Provides precise control over version information
• Set via -ldflags during go build

2. Runtime debug.BuildInfo (automatic fallback):

• Automatically used when ldflags are not set
• Extracts vcs.revision (git commit), vcs.time (build date), vcs.modified
• Available when building with Go 1.18+ and VCS information embedded
• Can be manually triggered via LoadFromBuildInfo()

Supported Version Formats:

1. Semantic Versioning (SemVer): vX.Y.Z format

• Example: v1.2.3, v2.0.0-alpha
• Follows semantic versioning specification

2. Calendar Versioning (CalVer): Various formats based on dates

• YYYY.MM.DD: v2024.10.02
• YY.MM.MICRO: v24.10.123
• YYYY.WW: v2024.42 (year and week number)
• YYYY.MM.DD.MICRO: v2024.10.02.456

The package automatically detects the version format and provides appropriate parsing, validation, and comparison functions. It includes functions to parse version components, validate version structs, compare versions, and extract semantic or calendar-based information from Git tags.

The module list is automatically populated at runtime using debug.BuildInfo (available since Go 1.12+), which extracts module dependencies embedded by the Go build system.

Typical usage involves setting the version variables during build with `-ldflags`, for example in a Makefile:

GIT_TAG := $(shell git describe --tags)
GIT_COMMIT := $(shell git rev-parse HEAD)
GIT_SHORT := $(shell git rev-parse --short HEAD)
BUILD_TIME := $(shell date +%FT%T%z)
VERSION_PACKAGE := github.com/valentin-kaiser/go-core/version

go build -ldflags "-X $(VERSION_PACKAGE).GitTag=$(GIT_TAG) \
                 -X $(VERSION_PACKAGE).GitCommit=$(GIT_COMMIT) \
                 -X $(VERSION_PACKAGE).GitShort=$(GIT_SHORT) \
                 -X $(VERSION_PACKAGE).BuildDate=$(BUILD_TIME)" main.go

The package defines the Release struct encapsulating all relevant fields, the ParsedVersion struct for version components, and the VersionParser interface for extensible version format support.

Example usage with different version formats:

// Get current version information
v := version.GetVersion()
fmt.Printf("App version: %s (commit %s)\n", v.GitTag, v.GitShort)
fmt.Printf("Format: %s\n", v.VersionFormat.String())

// Parse any supported version format
parsed, err := version.ParseVersion("v2024.10.02")
if err == nil {
	fmt.Printf("Year: %d, Month: %d, Day: %d\n", parsed.Year, parsed.Month, parsed.Day)
}

// Compare versions of the same format
result, err := version.CompareVersions("v1.2.3", "v1.2.4")
if err == nil && result < 0 {
	fmt.Println("First version is older")
}