go-version

go-version is HashiCorp’s Go library for working with software version strings. It parses version text into a structured Version type, compares versions correctly (including prerelease and metadata segments per SemVer rules), sorts collections of versions, and checks a version against one or more constraint expressions such as >= 1.0, < 2.0 or the pessimistic ~> 1.2 operator.

The library grew out of HashiCorp’s own tooling needs — it underpins version handling in projects like Terraform and Vault — and stays deliberately small: a handful of files, zero runtime dependencies, and a stable, well-documented public API. Recent releases added an opt-in WithPrefix option so callers can parse versions carrying a known prefix (like deployment-v1.2.3) without pre-processing the string themselves.

Because it implements encoding.TextMarshaler/TextUnmarshaler and database/sql’s Scanner/Valuer interfaces, Version values drop directly into JSON, YAML, and database columns without extra glue code, which is a big part of why it’s become a common building block anywhere a Go project needs to reason about version numbers.

What You Get

• A Version type with NewVersion/NewSemver parsers, plus Compare, LessThan, GreaterThan, Equal, and related comparison methods
• A Constraint/Constraints type parsed from strings like >= 1.0, < 1.4 with Check(v) to test a version against them
• Operators covering equality, inequality, ordering, and the pessimistic ~> (approximately-greater-than) operator
• A Collection type implementing sort.Interface so slices of versions can be sorted with the standard library’s sort package
• encoding.TextMarshaler/TextUnmarshaler and database/sql Scanner/Valuer implementations for drop-in JSON and database use
• An opt-in WithPrefix option (added in v1.9.0) for parsing versions that carry a known non-numeric prefix

Common Use Cases

• Validating that a user- or config-supplied version string satisfies a required range before running an operation
• Sorting a list of release tags or module versions into correct semantic order
• Implementing update-checkers or dependency resolvers that need accurate version comparison, including prerelease handling
• Storing and retrieving version values from a SQL database column via the Scanner/Valuer interfaces
• Parsing versions with custom deployment or component prefixes without manual string trimming

Under The Hood

Architecture The library is deliberately flat: four source files (version.go, constraint.go, version_collection.go, plus a small options block) with no internal package boundaries. Version is the core data type, storing parsed segments, prerelease, metadata, original string, and an optional prefix; parsing happens once through a shared newVersion helper driven by lazily-compiled regular expressions (versionRegexpOnce/semverRegexpOnce via sync.Once) so the cost of building the pattern is paid only on first use. Constraint wraps a Version plus an operator function (constraintFunc), and NewConstraint splits a comma-separated string into a Constraints slice, each element independently parsed by parseSingle. Collection is a thin adapter implementing sort.Interface over []*Version, delegating ordering to Version.LessThan. There is no dependency injection or layering to speak of — the design is a single cohesive value type with methods, which is appropriate for a parsing/comparison library; changing the core Compare logic would ripple into every constraint operator function since they all call Compare/LessThan under the hood.

Tech Stack Pure standard-library Go: regexp for pattern matching, strconv for numeric parsing, strings for splitting/trimming, sort for the Collection sort interface, sync for one-time regex compilation, and database/sql/driver to implement Scanner/Valuer. The go.mod declares go 1.16 as the minimum version and lists zero external dependencies — nothing to vendor, no supply-chain surface beyond Go itself. Build tooling is a small Makefile plus a GitHub Actions workflow (go-tests.yml) that runs the test suite and a copywrite.yml workflow that checks license headers, HashiCorp’s standard OSS repo hygiene setup.

Code Quality Testing is thorough relative to the codebase size: roughly 1,220 lines across three _test.go files against about 800 lines of implementation, with 31 top-level Test* functions covering version parsing edge cases, prerelease/metadata comparison, constraint operators (including the pessimistic ~> operator and prerelease-aware constraint matching), and collection sorting. Error handling is explicit and idiomatic — parsing functions return (*Version, error) / (*Constraint, error) rather than panicking, with a separate Must/MustConstraints panic-wrapper offered for callers who want the shortcut. Naming is consistent and exported symbols carry full doc comments suitable for pkg.go.dev. CI runs the test suite on every push/PR via GitHub Actions, and a license-header check (copywrite) enforces consistency across files.

What Makes It Unique The library goes beyond strict SemVer by accepting a wider, more permissive version grammar (VersionRegexpRaw) alongside a strict SemverRegexpRaw used by NewSemver, which lets it parse the messier version strings seen in the wild (Terraform providers, Vault plugins, arbitrary CLI tools) while still offering a strict-mode entry point when needed. Its pessimistic ~> constraint operator mirrors Bundler/RubyGems conventions, a comparison idiom not built into Go’s standard library or most peer version-parsing packages. The newer WithPrefix option is a targeted, narrowly-scoped addition rather than general prefix-stripping magic — it validates the prefix is actually present before stripping it, and keeps the parsed prefix retrievable via Prefix(), which is a deliberate API design choice for correctness-conscious callers. Combined with native database and text-marshaling interface support, it is more of an infrastructure-tooling foundation than a generic SemVer parser.