README
¶
Xver
Package xver provides information about an application upon a JSON structure that looks like:
{
"app": {
"name": "example",
"version": "1.2.0"
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"commit": "a9139a022be172adb222e84eda2d8808fbeb01e0",
"date": "2025-06-05T21:03:40Z"
}
}
You can set the app name, app version, build date and commit with -X build flags like:
go build -ldflags="-s -w -X 'github.com/actforgood/xver.name=example' -X 'github.com/actforgood/xver.version=1.2.0' -X 'github.com/actforgood/xver.date=2025-06-05T21:03:40Z' -X 'github.com/actforgood/xver.commit=a9139a0'" -o example /path/to/example-app/cmd/main.go
Installation
$ go get github.com/actforgood/xver
Example
A basic demo app can be setup with ./scripts/demoapp.sh included in the repo, and different behaviors on what information is available by default using the different build / run / install commands can be observed.
Output
>>> Creating demoapp in /Users/JohnDoe/go/xver/scripts/../bin/demoapp/
>>> Initializing git repo for it and tagging to v1.2.3
>>> 1. go build
{
"app": {
"name": "demoapp",
"version": "1.2.3"
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"commit": "addaf89ed0461cdadbf74214e217899bfc04dcad",
"date": "2025-06-06T08:33:53Z"
}
}
>>> 2. go run main.go
{
"app": {
"name": "main",
"version": ""
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"date": ""
}
}
>>> 3. go install
{
"app": {
"name": "demoapp",
"version": "1.2.3"
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"commit": "addaf89ed0461cdadbf74214e217899bfc04dcad",
"date": "2025-06-06T08:33:53Z"
}
}
>>> 4. Creating a new file causing the repo to be dirty & go build
{
"app": {
"name": "demoapp",
"version": "1.2.3+dirty"
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"commit": "addaf89ed0461cdadbf74214e217899bfc04dcad",
"date": "2025-06-06T08:33:53Z"
}
}
>>> 5. Setting information via flags
>>> go build -ldflags="-s -w -X 'github.com/actforgood/xver.name=my-demo-app' -X 'github.com/actforgood/xver.version=9.8.7' -X 'github.com/actforgood/xver.date=2025-06-05T21:58:45Z' -X 'github.com/actforgood/xver.commit=a9139a0'" -o demoapp main.go
{
"app": {
"name": "my-demo-app",
"version": "9.8.7"
},
"build": {
"go": "1.24.3",
"arch": "amd64",
"os": "darwin",
"commit": "a9139a0",
"date": "2025-06-05T21:58:45Z"
}
}
Example of a little code snipped for printing version from cmd line arguments
package main
import (
"encoding/json"
"fmt"
"os"
"github.com/actforgood/xver"
)
func main() {
PrintVersion()
// ...
}
func PrintVersion() {
if len(os.Args) < 2 || os.Args[1] != "version" {
return
}
info := xver.Information()
var output string
if len(os.Args) > 2 && os.Args[2] == "--json" {
infoJSON, _ := json.Marshal(info)
output = string(infoJSON)
} else {
output = fmt.Sprintf(
"%s/%s (%s/%s)",
info.App.Name, info.App.Version,
info.Build.OS, info.Build.Arch,
)
}
fmt.Println(output)
os.Exit(0)
}
// Example of output for `./demoapp version`:
// demoapp/1.2.3 (darwin/amd64)
//
// Example of output for `./demoapp version --json`:
// {"app":{"name":"demoapp","version":"1.2.3"},"build":{"go":"1.24.3","arch":"amd64","os":"darwin","commit":"34091f1484780b4e8990df6e1d50f2bc6181430b","date":"2025-06-06T09:48:30Z"}}
Example of a little code snipped for printing web server information
package main
import (
"encoding/json"
"log"
"net/http"
"github.com/actforgood/xver"
)
func main() {
hdlr := http.NewServeMux()
hdlr.HandleFunc("/info", InfoHandleFunc)
// ...
srv := &http.Server{
Addr: ":8080",
Handler: hdlr,
}
log.Fatal(srv.ListenAndServe())
}
func InfoHandleFunc(w http.ResponseWriter, r *http.Request) {
info := xver.Information()
enc := json.NewEncoder(w)
_ = enc.Encode(info)
}
// Example of output for `curl http://127.0.0.1:8080/info`:
// {"app":{"name":"demoapp","version":"1.2.3"},"build":{"go":"1.24.3","arch":"amd64","os":"darwin","commit":"34091f1484780b4e8990df6e1d50f2bc6181430b","date":"2025-06-06T09:48:30Z"}}`
Misc
Feel free to use this pkg if you like it and it fits your needs.
As it is a light/lite pkg, you can also just copy-paste the code instead of importing it, keeping the license header.
License
This package is released under a MIT license. See LICENSE.
Documentation
¶
Overview ¶
Package xver stores the project's information like version, name, and build.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// Name holds the application name.
// Defaults to executable name.
//
// You can set it during build time with -X 'github.com/actforgood/xver.name=<appName>'.
Name string `json:"name"`
// Version holds the application version.
// Defaults to [debug.BuildInfo.Main.Version].
//
// You can set it during build time with -X 'github.com/actforgood/xver.version=<appVersion>'.
//
// Note from go1.24 release:
// The go build command now sets the main module’s version in the compiled binary based on
// the version control system tag and/or commit. A +dirty suffix will be appended if there
// are uncommitted changes. Use the -buildvcs=false flag to omit version control information
// from the binary.
Version string `json:"version"`
}
App holds basic application information, like name and version.
type Build ¶
type Build struct {
// Go holds the go version application was compiled with.
//
// It is taken from [debug.ReadBuildInfo], if available.
Go string `json:"go"`
// Arch is the architecture binary was build for.
//
// It is taken from [debug.ReadBuildInfo], if available.
Arch string `json:"arch"`
// OS is the operating system binary was build for.
//
// It is taken from [debug.ReadBuildInfo], if available.
OS string `json:"os"`
// Commit is the commit sha.
//
// It is taken from [debug.ReadBuildInfo], if available.
//
// You can set it during build time with -X 'github.com/actforgood/xver.commit=<gitCommit>'.
Commit string `json:"commit,omitempty"`
// Date is application build date.
//
// It is taken from [debug.ReadBuildInfo], if available.
//
// You can set it during build time with -X 'github.com/actforgood/xver.date=<buildDate>'.
Date string `json:"date"`
}
Build holds basic build information, like the go version used and application built time.
type Info ¶
type Info struct {
// App holds app info.
App App `json:"app"`
// Build holds build info.
Build Build `json:"build"`
}
Info holds basic build information about an application.
Some information may not be available, by default.
To set the app name / app version / build date you can use `-X` option when running `go build` cmd.
Source Files
Click to show internal directories.
Click to hide internal directories.