semver

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package semver provides immutable semantic versioning types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeFormatValues 

func ComputeFormatValues(ver SemanticVersion, cfg FormatConfig) map[string]string

ComputeFormatValues computes all output variable strings from a semantic version. This is a pure function with no side effects.

Types

type BuildMetaData 

type BuildMetaData struct {
	CommitsSinceTag           *int64
	Branch                    string
	Sha                       string
	ShortSha                  string
	VersionSourceSha          string
	CommitDate                time.Time
	CommitsSinceVersionSource int64
	UncommittedChanges        int64
}

BuildMetaData represents the build metadata of a semantic version. This type is immutable — all methods return new values.

func (BuildMetaData) FullString 

func (m BuildMetaData) FullString() string

FullString returns the complete metadata string including branch and SHA. Format: "5.Branch.main.Sha.abc1234"

func (BuildMetaData) Padded 

func (m BuildMetaData) Padded(pad int) string

Padded returns the metadata string with zero-padded commits since tag.

func (BuildMetaData) String 

func (m BuildMetaData) String() string

String returns the short metadata string (commits since tag count).

type CommitMessageConvention 

type CommitMessageConvention int

CommitMessageConvention controls which commit message conventions are used for version incrementing. 

const (
	CommitMessageConventionConventionalCommits CommitMessageConvention = iota
	CommitMessageConventionBumpDirective
	CommitMessageConventionBoth
)

func ParseCommitMessageConvention 

func ParseCommitMessageConvention(s string) (CommitMessageConvention, error)

ParseCommitMessageConvention parses a string into a CommitMessageConvention. Matching is case-insensitive. Accepts hyphenated forms (e.g. "conventional-commits").

func (CommitMessageConvention) String 

func (c CommitMessageConvention) String() string

func (*CommitMessageConvention) UnmarshalYAML 

func (c *CommitMessageConvention) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for CommitMessageConvention.

type CommitMessageIncrementMode 

type CommitMessageIncrementMode int

CommitMessageIncrementMode controls how commit messages affect version incrementing. 

const (
	CommitMessageIncrementEnabled CommitMessageIncrementMode = iota
	CommitMessageIncrementDisabled
	CommitMessageIncrementMergeMessageOnly
)

func ParseCommitMessageIncrementMode 

func ParseCommitMessageIncrementMode(s string) (CommitMessageIncrementMode, error)

ParseCommitMessageIncrementMode parses a string into a CommitMessageIncrementMode. Matching is case-insensitive.

func (CommitMessageIncrementMode) String 

func (m CommitMessageIncrementMode) String() string

func (*CommitMessageIncrementMode) UnmarshalYAML 

func (m *CommitMessageIncrementMode) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for CommitMessageIncrementMode.

type FormatConfig 

type FormatConfig struct {
	// Padding is the number of digits for zero-padded fields (default: 4).
	Padding int
	// CommitDateFormat is the format for commit dates (default: "2006-01-02").
	// Accepts Go time layouts or .NET/Java-style formats (e.g. "yyyy-MM-dd").
	CommitDateFormat string
	// TagPreReleaseWeight is added to pre-release numbers for weighted sorting (default: 60000).
	TagPreReleaseWeight int64
}

FormatConfig holds configuration for computing format values.

func DefaultFormatConfig 

func DefaultFormatConfig() FormatConfig

DefaultFormatConfig returns a FormatConfig with default values.

type IncrementStrategy 

type IncrementStrategy int

IncrementStrategy represents the configured increment strategy for a branch. 

const (
	IncrementStrategyNone IncrementStrategy = iota
	IncrementStrategyMajor
	IncrementStrategyMinor
	IncrementStrategyPatch
	IncrementStrategyInherit
)

func ParseIncrementStrategy 

func ParseIncrementStrategy(s string) (IncrementStrategy, error)

ParseIncrementStrategy parses a string into an IncrementStrategy. Matching is case-insensitive.

func (IncrementStrategy) String 

func (s IncrementStrategy) String() string

func (IncrementStrategy) ToVersionField 

func (s IncrementStrategy) ToVersionField() VersionField

ToVersionField converts an IncrementStrategy to a VersionField. Inherit and None both map to VersionFieldNone.

func (*IncrementStrategy) UnmarshalYAML 

func (s *IncrementStrategy) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for IncrementStrategy.

type MainlineIncrementMode 

type MainlineIncrementMode int

MainlineIncrementMode controls how mainline mode applies version increments. 

const (
	// MainlineIncrementAggregate finds the highest increment from all commits
	// since the last tag and applies it once. Commit count goes into build metadata.
	MainlineIncrementAggregate MainlineIncrementMode = iota
	// MainlineIncrementEachCommit increments the version for each commit
	// individually.
	MainlineIncrementEachCommit
)

func ParseMainlineIncrementMode 

func ParseMainlineIncrementMode(s string) (MainlineIncrementMode, error)

ParseMainlineIncrementMode parses a string into a MainlineIncrementMode. Matching is case-insensitive. Accepts hyphenated forms (e.g. "each-commit").

func (MainlineIncrementMode) String 

func (m MainlineIncrementMode) String() string

func (*MainlineIncrementMode) UnmarshalYAML 

func (m *MainlineIncrementMode) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for MainlineIncrementMode.

type PreReleaseTag 

type PreReleaseTag struct {
	Name   string
	Number *int64
}

PreReleaseTag represents the pre-release portion of a semantic version. This type is immutable — all methods return new values.

func (PreReleaseTag) CompareTo 

func (t PreReleaseTag) CompareTo(other PreReleaseTag) int

CompareTo compares two PreReleaseTags. Returns a negative value, zero, or a positive value. A stable version (no tag) is greater than a pre-release version. Pre-release versions are compared by name (case-insensitive), then by number.

func (PreReleaseTag) HasTag 

func (t PreReleaseTag) HasTag() bool

HasTag returns true when the pre-release tag has a name or number.

func (PreReleaseTag) Legacy 

func (t PreReleaseTag) Legacy() string

Legacy returns the pre-release string without a dot separator (e.g., "beta4").

func (PreReleaseTag) LegacyPadded 

func (t PreReleaseTag) LegacyPadded(pad int) string

LegacyPadded returns the legacy format with zero-padded number (e.g., "beta0004").

func (PreReleaseTag) String 

func (t PreReleaseTag) String() string

String returns the dotted pre-release string (e.g., "beta.4").

func (PreReleaseTag) WithName 

func (t PreReleaseTag) WithName(name string) PreReleaseTag

WithName returns a new PreReleaseTag with the given name.

func (PreReleaseTag) WithNumber 

func (t PreReleaseTag) WithNumber(n int64) PreReleaseTag

WithNumber returns a new PreReleaseTag with the given number.

type SemanticVersion 

type SemanticVersion struct {
	Major         int64
	Minor         int64
	Patch         int64
	PreReleaseTag PreReleaseTag
	BuildMetaData BuildMetaData
}

SemanticVersion represents a semantic version. This type is immutable — all methods return new values.

func Parse 

func Parse(s, tagPrefix string) (SemanticVersion, error)

Parse parses a version string with an optional tag prefix regex. If tagPrefix is non-empty, the string must start with a match for the prefix.

func TryParse 

func TryParse(s, tagPrefix string) (SemanticVersion, bool)

TryParse attempts to parse a version string with an optional tag prefix regex. If tagPrefix is non-empty, the string must start with a match for the prefix. Returns the parsed version and true if successful.

func (SemanticVersion) CompareTo 

func (v SemanticVersion) CompareTo(other SemanticVersion) int

CompareTo compares two SemanticVersions. Returns a negative value, zero, or a positive value. Build metadata is not considered in comparisons per SemVer 2.0 spec.

func (SemanticVersion) FullSemVer 

func (v SemanticVersion) FullSemVer() string

FullSemVer returns the SemVer with build metadata (e.g., "1.2.3-beta.4+5").

func (SemanticVersion) IncrementField 

func (v SemanticVersion) IncrementField(field VersionField) SemanticVersion

IncrementField bumps the specified version field. Higher fields are preserved, lower fields are zeroed. Pre-release tag and build metadata are cleared. VersionFieldNone returns the version unchanged.

func (SemanticVersion) IncrementPreRelease 

func (v SemanticVersion) IncrementPreRelease() SemanticVersion

IncrementPreRelease bumps the pre-release number. Panics if the version has no pre-release number.

func (SemanticVersion) InformationalVersion 

func (v SemanticVersion) InformationalVersion() string

InformationalVersion returns the full informational string (e.g., "1.2.3-beta.4+5.Branch.main.Sha.abc1234").

func (SemanticVersion) LegacySemVer 

func (v SemanticVersion) LegacySemVer() string

LegacySemVer returns the legacy format without dots in pre-release (e.g., "1.2.3-beta4").

func (SemanticVersion) LegacySemVerPadded 

func (v SemanticVersion) LegacySemVerPadded(pad int) string

LegacySemVerPadded returns the padded legacy format (e.g., "1.2.3-beta0004").

func (SemanticVersion) SemVer 

func (v SemanticVersion) SemVer() string

SemVer returns the SemVer 2.0 format (e.g., "1.2.3" or "1.2.3-beta.4").

func (SemanticVersion) WithBuildMetaData 

func (v SemanticVersion) WithBuildMetaData(meta BuildMetaData) SemanticVersion

WithBuildMetaData returns a new SemanticVersion with the given build metadata.

func (SemanticVersion) WithPreReleaseTag 

func (v SemanticVersion) WithPreReleaseTag(tag PreReleaseTag) SemanticVersion

WithPreReleaseTag returns a new SemanticVersion with the given pre-release tag.

type VersionField 

type VersionField int

VersionField represents which field of a semantic version to increment. 

const (
	VersionFieldNone VersionField = iota
	VersionFieldPatch
	VersionFieldMinor
	VersionFieldMajor
)

func (VersionField) String 

func (f VersionField) String() string

type VersioningMode 

type VersioningMode int

VersioningMode represents the versioning mode. 

const (
	VersioningModeContinuousDelivery VersioningMode = iota
	VersioningModeContinuousDeployment
	VersioningModeMainline
)

func ParseVersioningMode 

func ParseVersioningMode(s string) (VersioningMode, error)

ParseVersioningMode parses a string into a VersioningMode. Matching is case-insensitive.

func (VersioningMode) String 

func (m VersioningMode) String() string

func (*VersioningMode) UnmarshalYAML 

func (m *VersioningMode) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for VersioningMode.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.