README
¶
version
Build-time version information with Git metadata, derived from embedded build info (debug.ReadBuildInfo), optionally overridden at link time via an unexported seam.
Install
go get github.com/kbukum/gokit
Quick Start
package main
import (
"fmt"
"github.com/kbukum/gokit/version"
)
func main() {
info := version.GetVersionInfo()
fmt.Println(info.Version) // e.g. "1.2.3"
fmt.Println(info.GitCommit) // e.g. "abc1234"
fmt.Println(info.GitBranch) // e.g. "main"
fmt.Println(version.GetShortVersion()) // "1.2.3-abc1234"
fmt.Println(version.GetFullVersion()) // "1.2.3-abc1234 (main, 2024-01-15)"
}
Build with ldflags:
go build -ldflags "-X github.com/kbukum/gokit/version.buildVersion=1.2.3 \
-X github.com/kbukum/gokit/version.buildGitCommit=$(git rev-parse --short HEAD) \
-X github.com/kbukum/gokit/version.buildGitBranch=$(git rev-parse --abbrev-ref HEAD) \
-X github.com/kbukum/gokit/version.buildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
Key Types & Functions
| Name | Description |
|---|---|
VersionInfo |
Struct with Version, GitCommit, GitBranch, BuildTime, GoVersion, BuildDate, IsRelease, IsDirty |
GetVersionInfo() |
Returns full *VersionInfo struct |
GetShortVersion() |
Returns version-commit string |
GetFullVersion() |
Returns detailed version string |
ParseVersion(v) / ParseRequirement(req) |
Parse a semantic version or a constraint requirement |
MatchesRequirement(v, req) |
Report whether a version satisfies a requirement (e.g. ">=1.2.0, <2.0.0") |
SupportedSchema[T](field, configured, supported) |
Validate a configured schema/format version against this build's supported value |
buildVersion / buildGitCommit / buildGitBranch / buildTime |
Unexported link-time override seam (no runtime mutation) |
Documentation
¶
Overview ¶
Package version provides immutable build metadata for gokit applications.
Version information is derived from the module's embedded build information (debug.ReadBuildInfo) — VCS revision, modification state, and build time. Release builds may override the defaults at link time via an unexported seam; there is no runtime-mutable version state:
go build -ldflags "-X github.com/kbukum/gokit/version.buildVersion=1.0.0 \ -X github.com/kbukum/gokit/version.buildGitCommit=$(git rev-parse --short HEAD)"
Use GetVersionInfo for the full VersionInfo, or GetShortVersion / GetFullVersion for formatted strings.
Semantic versions ¶
ParseVersion, ParseRequirement, and MatchesRequirement parse semantic versions and constraint requirements (for example ">=1.2.0, <2.0.0") and test a version against them. SupportedSchema validates a configured schema/format version against the one this build supports, returning a typed error on mismatch.
Index ¶
- func GetFullVersion() string
- func GetShortVersion() string
- func MatchesRequirement(version, requirement string) (bool, error)
- func ParseRequirement(requirement string) (*semver.Constraints, error)
- func ParseVersion(value string) (*semver.Version, error)
- func SupportedSchema[T comparable](field string, configured *T, supported T) (T, error)
- type VersionInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetFullVersion ¶
func GetFullVersion() string
GetFullVersion returns a detailed version string including branch and build date when available.
func GetShortVersion ¶
func GetShortVersion() string
GetShortVersion returns a compact version string of the form "<version>[-<commit>][-dirty]".
func MatchesRequirement ¶
MatchesRequirement reports whether version satisfies requirement. It returns an error when either input cannot be parsed.
func ParseRequirement ¶
func ParseRequirement(requirement string) (*semver.Constraints, error)
ParseRequirement parses a semantic version requirement such as ">=1.2", "^1.2", or "1.2.x". The returned error preserves the underlying parse cause.
func ParseVersion ¶
ParseVersion parses a strict semantic version string (MAJOR.MINOR.PATCH with optional pre-release and build metadata). Partial versions such as "1.2" are rejected. The returned error preserves the underlying parse cause.
func SupportedSchema ¶
func SupportedSchema[T comparable](field string, configured *T, supported T) (T, error)
SupportedSchema returns the configured schema version, or supported when configured is nil, rejecting any value the current code does not support.
It is a general-purpose gate for versioned documents (config files, manifests, on-disk formats) that declare a schema field and must reject any version the current code cannot safely interpret. This is distinct from semantic-version parsing: a schema version is typically a small monotonic integer, so the gate is generic over any comparable value.
A nil configured value defaults to supported. A configured value that differs from supported yields a typed invalid-input AppError.
Types ¶
type VersionInfo ¶
type VersionInfo struct {
Version string `json:"version"`
GitCommit string `json:"git_commit"`
GitBranch string `json:"git_branch"`
BuildTime string `json:"build_time"`
GoVersion string `json:"go_version"`
BuildDate time.Time `json:"build_date"`
IsRelease bool `json:"is_release"`
IsDirty bool `json:"is_dirty"`
}
VersionInfo is immutable build metadata describing the running binary.
func GetVersionInfo ¶
func GetVersionInfo() *VersionInfo
GetVersionInfo returns immutable version information for the running binary, derived from link-time overrides when present and otherwise from the embedded build information (VCS revision, modification state, and build time).
func (*VersionInfo) Full ¶
func (v *VersionInfo) Full() string
Full returns a detailed version string including a non-default branch, dirty state, and build date when available.
func (*VersionInfo) Short ¶
func (v *VersionInfo) Short() string
Short returns a compact version string of the form "<version>[-<commit>][-dirty]".
Source Files