Documentation ¶
Overview ¶
version module provides some API to help Go Application get it's version with zero-cost.
After Go 1.15, version information for applications written in Go is available from its own binary. This is a very useful feature, but I've noticed that almost no one in the community at large uses it.
I think this is probably because runtime/debug.BuildInfo is harder to use directly, and the community doesn't have a ready-made library to simplify this. So I wrote this module to help people easily get the version information of their Go programs. Of course, based on the go module version control policy and semantic version.
See also:
- Go Modules Reference: https://go.dev/ref/mod
- Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrintVersion ¶
PrintVersion combines information from GetAppVersion() and GetVcsInfo(), it provides version information in a human-readable manner. User-supplied writer can extend the scope of PrintVersion, typically with os.Stderr.
brief and detail are two templates to allow control of the output format. PrintVersion uses text/template to generate the output and provides inputs for brief and detail respectively.
The default brief template is:
{{.AppName}} version {{.AppVersion}}, built with {{.GoVersion}}
Tnd default detail template is:
WARNING! This is not a release version, it's built from a {{.TagRemarks}}. VCS information: VCS: {{.VCS}} Module path: {{.ModulePath}} Commit time: {{.LastCommit.Local.Format "2006-01-02 15:04:05 MST"}} Revision id: {{.Revision}} Please visit {{.ModulePath}} to get updates.
PrintVersion always evaluates brief, and only evaluates detail if the tag is not a release and pre-release tag.
Types ¶
type Detail ¶
type Detail struct { Brief ModVersion VcsInfo TagRemarks string }
Detail provides the field to render a detail version information.
type ModVersion ¶
type ModVersion struct { Type VersionType Tag string CommitID string Time time.Time }
ModVersion represents the information retrieved from debug.Module.Version.
func GetAppVersion ¶
func GetAppVersion(version string) (verInfo *ModVersion)
GetAppVersion get Go Application Version from Go binary via debug.BuildInfo.
A Go Module Version string layout is one of follow formats:
- dirty vcs work directory: (devel)
- release version: vX.Y.Z
- pre-release version: v1.2.3-RC1
- pseudo version:
- untagged branch: v0.0.0-YYYYmmddHHMMSS-aabbccddeeff
- base on release version: vX.Y.(Z+1)-0.YYYYmmddHHMMSS-aabbccddeeff
- base on pre-release version: vX.Y.Z-RC1.0.YYYYmmddHHMMSS-aabbccddeeff
See also: https://go.dev/ref/mod#glossary
type VcsInfo ¶
VcsInfo represents the information retrieved from debug.BuildSetting.
func GetVcsInfo ¶
func GetVcsInfo(settings []debug.BuildSetting) *VcsInfo
GetVcsInfo extract VCS information from debug.BuildSetting. if settings is nil, GetVcsInfo will call debug.ReadBuildInfo() by itself.
type VersionType ¶
type VersionType int
VersionType indicate the type of Version, there are six valid VersionTypes:
- Devel
- Release
- PreRelease
- PseudoBaseNoTag
- PseudoBaseRelease
- PseudoBasePreRelease
const ( Devel VersionType = iota // built via `go build` Release // built via `go install` with a release tag PreRelease // built via `go install` with a pre-release tag PseudoBaseNoTag // built via `go install` without any tag PseudoBaseRelease // built on several patches after a release tag PseudoBasePreRelease // built on several patches after a pre-release tag ErrorVersion // some errors have occurred )