version

Documentation

Overview

Package version provides build metadata and version information management.

This package manages application version information including semantic version, Git revision, build time, and provides integration with CLI frameworks (Cobra, Kong) and Prometheus metrics for operational visibility.

Version information can be injected at build time using ldflags:

go build -ldflags "-X go.ntppool.org/common/version.VERSION=v1.0.0 \
  -X go.ntppool.org/common/version.buildTime=2023-01-01T00:00:00Z \
  -X go.ntppool.org/common/version.gitVersion=abc123"

The package also automatically extracts build information from Go's debug.BuildInfo when available, providing fallback values for VCS time and revision.

Index

• Variables
• func CheckVersion(version, minimumVersion string) bool
• func RegisterMetric(name string, registry prometheus.Registerer)
• func Version() string
• func VersionCmd(name string) *cobra.Command
• type Info
  • func VersionInfo() Info
• type KongVersionCmd
  • func (cmd *KongVersionCmd) Run() error

Variables

var (
	VERSION string // Semantic version (e.g., "1.0.0" or "v1.0.0")

)

VERSION contains the current software version (typically set during the build process via ldflags). If not set, defaults to "dev-snapshot". The version should follow semantic versioning.

Functions

func CheckVersion

func CheckVersion(version, minimumVersion string) bool

CheckVersion compares a version against a minimum required version. Returns true if the version meets or exceeds the minimum requirement.

Special handling:

• "dev-snapshot" is always considered valid (returns true)
• Git hash suffixes (e.g., "v1.0.0/abc123") are stripped before comparison
• Uses semantic version comparison rules

Both version and minimumVersion should follow semantic versioning with "v" prefix.

func RegisterMetric

func RegisterMetric(name string, registry prometheus.Registerer)

RegisterMetric registers a Prometheus gauge metric with build information. If name is provided, it creates a metric named "{name}_build_info", otherwise "build_info". The metric includes labels for version, build time, Git time, and Git revision. This is useful for exposing build information in monitoring systems.

func Version

func Version() string

Version returns a human-readable version string suitable for display. The format includes semantic version, Git revision, build time, and Go version. Example: "v1.0.0/abc123f-M (2023-01-01T00:00:00Z, go1.21.0)" The "-M" suffix indicates the working tree was modified during build.

func VersionCmd

func VersionCmd(name string) *cobra.Command

VersionCmd creates a Cobra command for displaying version information. The name parameter is used as a prefix in the output (e.g., "myapp v1.0.0"). Returns a configured cobra.Command that can be added to any CLI application.

Types

type Info

type Info struct {
	Version     string `json:",omitempty"` // Semantic version with "v" prefix
	GitRev      string `json:",omitempty"` // Full Git commit hash
	GitRevShort string `json:",omitempty"` // Shortened Git commit hash (7 characters)
	BuildTime   string `json:",omitempty"` // Build timestamp
}

Info represents structured version and build information. This struct is used for JSON serialization and programmatic access to build metadata.

func VersionInfo

func VersionInfo() Info

VersionInfo returns the structured version information. This provides programmatic access to version details for JSON serialization or other structured uses.

type KongVersionCmd

type KongVersionCmd struct {
	Name string `kong:"-"` // Application name, excluded from Kong parsing
}

KongVersionCmd provides a Kong CLI framework compatible version command. The Name field should be set to the application name for proper output formatting.

func (*KongVersionCmd) Run

func (cmd *KongVersionCmd) Run() error

Run executes the version command for Kong CLI framework. Prints the application name and version information to stdout.