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 version [--dir <path>] [--ref <ref>]
  gitsemver next <patch|minor|major|patch-rc|minor-rc|major-rc|rc|rc-release> [--last-tag <tag>]
  gitsemver validate [--type dev|rc|stable|any] <version>
  gitsemver completion <bash|zsh|fish|powershell>

version

Print the version for a git ref:

  --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")

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

$ gitsemver version --ref v1.2.3
1.2.3

next

Compute the next semver release tag after the highest-semver tag reachable from HEAD:

$ gitsemver next patch          # v1.2.3 ancestor → prints 1.2.4
$ gitsemver next minor-rc       # v1.2.3 ancestor → prints 1.3.0-rc.1
$ gitsemver next rc             # v1.3.0-rc.1 ancestor → prints 1.3.0-rc.2
$ gitsemver next rc-release     # v1.3.0-rc.1 ancestor → prints 1.3.0

Use --last-tag to supply the base explicitly — no git repository needed:

$ gitsemver next patch --last-tag v1.2.3
1.2.4

Valid bump types:

Base tag	Bump type	Result
Stable X.Y.Z	patch	X.Y.Z+1
Stable X.Y.Z	minor	X.Y+1.0
Stable X.Y.Z	major	X+1.0.0
Stable X.Y.Z	patch-rc	X.Y.Z+1-rc.1
Stable X.Y.Z	minor-rc	X.Y+1.0-rc.1
Stable X.Y.Z	major-rc	X+1.0.0-rc.1
RC X.Y.Z-rc.N	rc	X.Y.Z-rc.N+1
RC X.Y.Z-rc.N	rc-release	X.Y.Z

When no version tag is reachable from HEAD, 0.0.0 is used as the base. Note: rc and rc-release require an actual reachable RC tag and cannot be used from the implicit 0.0.0 base — start a new RC series with patch-rc, minor-rc, or major-rc instead.

Shell completion

Generate and load a completion script for your shell:

# bash — add to ~/.bashrc
source <(gitsemver completion bash)

# zsh — add to ~/.zshrc (requires compinit to be loaded)
source <(gitsemver completion zsh)

# fish
gitsemver completion fish | source

# PowerShell — add to $PROFILE
gitsemver completion powershell | Out-String | Invoke-Expression

Once loaded, gitsemver next <TAB> completes bump types and gitsemver validate --type <TAB> completes version types.

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 version [--dir <path>] [--ref <ref>]
gitsemver next <bump-type> [--last-tag <tag>]
gitsemver validate [--type dev|rc|stable|any] <version>

The "version" subcommand 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 "next" subcommand computes the next semver tag from the highest-semver tag reachable from HEAD. Valid bump types from a stable tag: patch, minor, major, patch-rc, minor-rc, major-rc. Valid from an RC tag: rc, rc-release. Use --last-tag to skip git and compute directly from a supplied base tag.

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.

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". The "next --last-tag"
                    flag accepts both prefixed ("module-a/v1.2.3") and bare
                    ("v1.2.3") forms; the prefix is stripped automatically.