README ¶
semver
semver
reports details for a git repository as variables.
It retrieves non-changing details for the current build from git
and prints them.
These are
- HEAD commit revision
- HEAD commit timestamp (UTC)
- current branch
- semantic version based on tag
- are there uncommitted tracked files
Note: the branch is not necessarily deterministic, better avoid using it. Everyone can name it locally however they want. Might be useful on CI though.
Tags are only used for the semantic version.
They could also be moved - don't do that. Or if you are prone to do it, don't use
the Semver
field in the template.
We do not currently provide author or committer information or the commit message. That would grow the possible error cases and there was no clear use case yet.
Semantic versioning
It mainly helps with semantic versioning and it will show tags following a subset of the specification at https://semver.org/. The regular expression used is the one from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
Installation
You can install it with go get
or using Bazel: bazel build @iq_buildtools//cmd/semver
.
Templating
The default template is usable as output for a Bazel workspace_status command.
Call semver -help
to get details concerning its operation.
Path
If it is set (run from Bazel), it will change directories into the path referenced in
BUILD_WORKSPACE_DIRECTORY
before git is run. This is done to make sure the right repository
is used. The target directory can be changed using -dir
, see the help output below.
Default result
The output looks like this:
STABLE_COMMIT_ID 5833e2847a3ced66f119a79c84faa4f6e0c943fd
STABLE_COMMIT_TS 1586368369
STABLE_COMMIT_UTC 2020-04-08T17:52:49
STABLE_COMMIT_UTC_TAG 20200408175249
STABLE_COMMIT_BUILD 20200408175249.5833e284.1586455851
STABLE_COMMIT_SEMVER 0.0.0-20200408175249.5833e284.1586455851
STABLE_COMMIT_BRANCH master
STABLE_COMMIT_STATUS modified
Default help text
The help text currently looks like this:
Use semver to retrieve versioning information for the repository containing /mnt/space/src/bitbucket.org/vauwede/rulestack/cmd/semver
Git is used to retrieve the data. It must be available in your PATH.
Times used in the default template are UTC. Time errors are encoded as unix epoch.
Uncommitted files result in a version number v0.0.0
-debug
print detailed information for arguments and the data from git
-dir string
set execution directory (default "<DIRECTORY>")
-errlog
log failing git call details to stderr
-help
show this help text
-out string
output file, leave it empty for stdout
-ref string
git reference to a commit to operate on. For testing, should not be changed (default "HEAD")
-template string
path to a template file (text/template in Go). Empty for the default below
Check https://golang.ir/pkg/text/template for a template reference.
Two functions are supported: Now for the current time and Env to retrieve an environment variable.
The default template follows these conventions:
* time is always UTC
* time errors are encoded as Unix epoch (1970-01-01T00:00:00)
* unknown revisions consist of a series of "0"
* tracked but uncommitted files are not fit for a release version
* tracked but not committed files lead to a 0.0.0-... semver as they are not fit for release
The default template looks like this:
{{- define "tagregexp"}}
{{- /* regexp from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string plus optional leading "v"*/ -}}
^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
{{- end}}
{{- $now := Now}}
{{- $rev := "0000000000000000000000000000000000000000"}}{{- if ge (len .Revision) 40}}{{$rev = .Revision}}{{end}}
{{- $shortrev := slice $rev 0 8}}
{{- $timestamp := .Time.UTC.Unix}}
{{- $utc := .Time.UTC.Format "2006-01-02T15:04:05"}}
{{- $utctag := .Time.UTC.Format "20060102150405"}}
{{- $status := "modified"}}{{- if .Clean}}{{$status = "clean"}}{{end}}
{{- $devsuffix := ""}}{{- if eq false .Clean}}{{$devsuffix = printf ".%v" $now.Unix}}{{end}}
{{- $build := printf "%s.%s%s" $utctag (slice .Revision 0 8) $devsuffix}}
{{- $semver := .Semver}}{{- if or (not .Clean) (eq .Semver "")}}{{$semver = printf "0.0.0-%s" $build}}{{end}}
{{- if eq "v" (slice $semver 0 1)}}{{$semver = slice $semver 1}}{{end}}
{{- $branch := .Branch -}}
STABLE_COMMIT_ID {{$rev}}
STABLE_COMMIT_TS {{$timestamp}}
STABLE_COMMIT_UTC {{$utc}}
STABLE_COMMIT_UTC_TAG {{$utctag}}
STABLE_COMMIT_BUILD {{$build}}
STABLE_COMMIT_SEMVER {{$semver}}
STABLE_COMMIT_BRANCH {{$branch}}
STABLE_COMMIT_STATUS {{$status}}
Documentation ¶
There is no documentation for this package.