gitsemver

README

gitsemver

Library and CLI tool for computing a semVer-compatible version from a git reference.

Version format

Situation	Returned version
HEAD carries stable tag vX.Y.Z	X.Y.Z
HEAD carries pre-release tag vX.Y.Z-rc.N	X.Y.Z-rc.N
HEAD is untagged, stable ancestor vX.Y.Z reachable	X.Y.(Z+1)-dev.<branch>.<YYYY-MM-DD>.<HH-MM-SS>
HEAD is untagged, no stable ancestor reachable	0.0.0-dev.<branch>.<YYYY-MM-DD>.<HH-MM-SS>

For untagged commits the base is the most recent stable ancestor tag reachable from the ref (RC and other pre-release tags are skipped). When no stable ancestor exists the version prefix is 0.0.0 with no patch increment.

Environment variables

Variable	Effect
GS_BRANCH_NAME	Override the branch name embedded in dev build versions. Defaults to the HEAD branch of the repo, then "unknown".
GS_GIT_TAG_PREFIX	Monorepo support: only consider tags prefixed with "<value>/", e.g. module-a/v1.2.3.

CLI — gitsemver

go install github.com/giantswarm/gitsemver@latest

Usage: gitsemver [flags]

  -dir string   path inside the git repository (default ".", resolved to repo root)
  -ref string   git ref to resolve: branch name, tag, or commit SHA (default "HEAD")

Example — print the version for the current working tree:

$ GS_BRANCH_NAME=my-feature gitsemver
1.2.4-dev.my-feature.2026-01-27.09-49-59

$ gitsemver --ref v1.2.3
1.2.3

Go library

c := gitsemver.Config{
    Dir: "/path/to/some-repo",
    URL: "git@github.com:giantswarm/some-repo.git",
}
repo, err := gitsemver.New(c)
version, err := repo.ResolveVersion(ctx, "HEAD")
// e.g. "1.2.4-dev.my-feature.2026-01-27.09-49-59"

Documentation

Overview

gitsemver prints or validates semVer-compatible version strings for git refs.

Usage:

gitsemver [flags]
gitsemver validate [--type dev|rc|stable|any] <version>
gitsemver version

Without a subcommand it resolves and prints the version for a git ref:

For a ref that carries a stable tag (vX.Y.Z) it prints X.Y.Z.
For a pre-release tag (vX.Y.Z-rc.N) it prints X.Y.Z-rc.N.
For an untagged ref it prints a dev build:

    X.Y.(Z+1)-dev.<branch>.<YYYY-MM-DD>.<HH-MM-SS>

where X.Y.Z is the most recent stable ancestor tag reachable from the ref,
or 0.0.0 when none exists.

The "validate" subcommand checks whether a version string matches the expected format. It exits 0 and prints "valid" on success, exits 1 and prints "invalid" otherwise.

The "version" subcommand prints the build version (git tag), git SHA, and build timestamp embedded at link time.

Environment variables:

GS_BRANCH_NAME      Override the branch name embedded in dev builds.
                    Defaults to the HEAD branch of the repo, then "unknown".
GS_GIT_TAG_PREFIX   Monorepo support: only consider tags prefixed with
                    "<value>/", e.g. "module-a/v1.2.3".