semverish

README

go-semverish

---

Lenient version comparison for mod-loader ecosystems: loose semver as SMAPI and BepInEx read it, and .NET System.Version ordering. Package semverish, module github.com/Rethunk-Tech/go-semverish.

Mod authors and mod managers write versions loosely: v1.2, 1.0.0.1, 1.0-beta-2, 2.0-unofficial.3-author. semverish orders them the way SMAPI does, never panics on a string it cannot read, and says so (ok == false) instead of guessing. CompareDotNet orders them the way .NET's System.Version does, which BepInEx 5 uses. Standard library only.

Quick start

go get github.com/Rethunk-Tech/go-semverish

A worked example and the contracts: HUMANS.md.

Features

• Compare orders two strings, and Parse plus Version.Compare order without re-parsing.
• Two to four numbers, a missing number is 0, an optional v or V, build metadata ignored.
• SMAPI's prerelease rules: . and - both separate identifiers, unofficial ranks lowest.
• Prerelease numbers of any length compare by value, so a hostile string cannot break transitivity.
• CompareDotNet follows System.Version: 1.0 is below 1.0.0, and 1.0.0-beta is not a version.

Documentation

Doc	Audience
HUMANS.md	Running and using the package
AGENTS.md	Internals, invariants, and why
CONTRIBUTING.md	Process — commits, tests, docs
SECURITY.md	Vulnerability disclosure
CHANGELOG.md	Release notes

License

MIT — see LICENSE. © 2026 Rethunk.Tech, LLC.

Documentation

Overview

Package semverish orders version strings the way game mod loaders do: SMAPI's loose semantic versions (two to four numbers, an optional v, SMAPI's prerelease rules) and .NET's System.Version, which BepInEx 5 uses.

Index

• func Compare(a, b string) (c int, ok bool)
• func CompareDotNet(a, b string) (c int, ok bool)
• func Equal(a, b string) bool
• type Version
  • func Parse(s string) (Version, bool)
  • func (v Version) Compare(w Version) int
  • func (v Version) String() string

Functions

func Compare

func Compare(a, b string) (c int, ok bool)

Compare parses both strings and orders them as Version.Compare does. ok is false, and the order 0, when either does not parse.

func CompareDotNet

func CompareDotNet(a, b string) (c int, ok bool)

CompareDotNet orders two versions the way .NET's System.Version does, which BepInEx 5 uses: two to four plain numbers, a part left out ranks below 0 (so 1.0 < 1.0.0), and anything else (a suffix, a leading v, one number) is not a version. ok is false, and the order 0, when either is not one.

func Equal

func Equal(a, b string) bool

Equal reports whether a and b are the same version: both parse and compare equal ("1.2" and "1.2.0"), or, when either does not parse, the strings are identical.

Types

type Version

type Version struct {
	Major, Minor, Patch int
	// Platform is SMAPI's fourth number.
	Platform int
	// Pre and Build are written without their leading '-' and '+'. Build never affects order.
	Pre, Build string
}

Version is a parsed version. Missing numbers are 0.

func Parse

func Parse(s string) (Version, bool)

Parse reads a version: two to four numbers, an optional leading v or V, an optional -prerelease whose identifiers are separated by '.' or '-', and optional +build, with surrounding whitespace trimmed. Leading zeros are accepted.

func (Version) Compare

func (v Version) Compare(w Version) int

Compare orders v against w: -1, 0 or 1. A release outranks its prereleases, build metadata is ignored, and an "unofficial" identifier ranks below any other.

func (Version) String

func (v Version) String() string

String writes "M.m.p[.platform][-pre][+build]" without a v. The platform number is left out when 0.