Version sorting

Version Sorting

Setup: See /installation for one-time SDK/CLI/MCP install.
Layers: SDK (Go) → CLI (shell) → MCP (AI tools) — pick your entry point.

When to Use

• You have a list of version strings and need them in natural order
• You need to find the latest or oldest version in a collection
• You need to display versions in ascending or descending order
• You are implementing version selection UI or dependency resolution
• You need to sort versions read from a file

Decision Tree

Need to sort versions?
├─ Input is []string?                → SortVersionStringSlice() / versions sort / version_sort
├─ Input is []*Version?              → SortVersionSlice() or VersionSlice + sort.Sort()
├─ Need descending order?            → SortVersionStringSlice then reverse / --desc / descending:true
├─ Input is from a file?             → versions sort --from-file <path>
├─ Need to sort version groups?      → SortVersionGroupMap() or SortVersionGroupSlice()
└─ Need latest/oldest after sort?    → Sort ascending, then take first (oldest) or last (latest)

Task Patterns

Sort version strings in ascending order

Goal: Sort ["2.0.0", "1.0.0", "1.10.0", "1.2.0"] to ["1.0.0", "1.2.0", "1.10.0", "2.0.0"].

SDK approach:

sorted := versions.SortVersionStringSlice([]string{"2.0.0", "1.0.0", "1.10.0", "1.2.0"})
// sorted = ["1.0.0", "1.2.0", "1.10.0", "2.0.0"]
// Original slice is NOT modified

CLI approach:

versions sort 2.0.0 1.0.0 1.10.0 1.2.0
# Output: 1.0.0 1.2.0 1.10.0 2.0.0

MCP approach:

{"tool": "version_sort", "arguments": {"versions": ["2.0.0", "1.0.0", "1.10.0", "1.2.0"]}}

Sort in descending order (latest first)

Goal: Get ["2.0.0", "1.10.0", "1.2.0", "1.0.0"].

SDK approach:

sorted := versions.SortVersionStringSlice(versions)
// Then reverse in place or iterate backward
for i := len(sorted) - 1; i >= 0; i-- {
    fmt.Println(sorted[i])
}

CLI approach:

versions sort --desc 2.0.0 1.0.0 1.10.0 1.2.0
# Output: 2.0.0 1.10.0 1.2.0 1.0.0

MCP approach:

{"tool": "version_sort", "arguments": {"versions": ["2.0.0", "1.0.0", "1.10.0", "1.2.0"], "descending": true}}

Sort Version objects and find latest/oldest

Goal: Find the newest and oldest version in a collection of Version objects.

SDK approach:

versionList := versions.NewVersions("2.0.0", "1.0.0", "1.10.0")
sortedVersions := versions.SortVersionSlice(versionList)
latest := sortedVersions[len(sortedVersions)-1]  // 2.0.0
oldest := sortedVersions[0]                       // 1.0.0

CLI approach:

versions sort --desc 2.0.0 1.0.0 1.10.0 | head -1  # latest
versions sort 2.0.0 1.0.0 1.10.0 | head -1          # oldest

MCP approach:

{"tool": "version_sort", "arguments": {"versions": ["2.0.0", "1.0.0", "1.10.0"], "descending": true}}

Sort versions from a file

Goal: Read versions from releases.txt and sort them.

SDK approach:

// Use version_read_file to read, then sort
// See [[version-read-write]] for file I/O

CLI approach:

versions sort --from-file releases.txt
versions sort --desc --from-file releases.txt

MCP approach:

{"tool": "version_read_file", "arguments": {"file_path": "releases.txt"}}

Then pass the result to version_sort.

Use VersionSlice with standard library sort

Goal: Use Go's sort.Sort() directly on a version slice.

SDK approach:

slice := versions.VersionSlice(versions.NewVersions("3.0.0", "1.0.0", "2.0.0"))
sort.Sort(slice) // no closures needed — VersionSlice implements sort.Interface
// slice is now [1.0.0, 2.0.0, 3.0.0]

CLI approach: Not applicable — CLI handles sorting internally.

MCP approach: Not applicable — MCP handles sorting internally.

Sort version groups

Goal: Sort a map of version groups into a deterministic order.

SDK approach:

groupMap := versions.Group(versionList)
sortedGroups := versions.SortVersionGroupMap(groupMap)
for _, g := range sortedGroups {
    fmt.Println(g.ID()) // groups in sorted order
}

CLI approach:

versions group 1.0.0 1.1.0 2.0.0 2.1.0 3.0.0

MCP approach:

{"tool": "version_group", "arguments": {"versions": ["1.0.0", "1.1.0", "2.0.0", "2.1.0", "3.0.0"]}}

API Reference

SDK — Sort Functions

// Sort string slices — parses each, sorts, returns sorted strings.
// Does NOT modify the original slice. O(n) extra space.
func SortVersionStringSlice(versionStringSlice []string) []string

// Sort Version object slices — uses group-based algorithm.
// Does NOT modify the original slice.
func SortVersionSlice(versions []*Version) []*Version

// Convert a version group map to a sorted slice of VersionGroup objects.
func SortVersionGroupMap(versionGroupMap map[string]*VersionGroup) []*VersionGroup

// In-place sort of a VersionGroup slice. MODIFIES the input slice directly.
func SortVersionGroupSlice(groupSlice []*VersionGroup)

SDK — VersionSlice Type

// VersionSlice implements sort.Interface — use sort.Sort() directly, no closures needed.
type VersionSlice []*Version

func (s VersionSlice) Len() int
func (s VersionSlice) Less(i, j int) bool
func (s VersionSlice) Swap(i, j int)

// Additional methods beyond sort.Interface:
func (s VersionSlice) Min() *Version                    // oldest version
func (s VersionSlice) Max() *Version                    // newest version
func (s VersionSlice) Filter(predicate func(*Version) bool) VersionSlice
func (s VersionSlice) Contains(target *Version) bool
func (s VersionSlice) IndexOf(target *Version) int
func (s VersionSlice) Unique() VersionSlice
func (s VersionSlice) Sort()                            // sort in-place
func (s VersionSlice) Sorted() VersionSlice             // return sorted copy

CLI Commands

# Sort version strings in ascending order
versions sort <version1> <version2> ... <versionN>

# Sort in descending order (latest first)
versions sort --desc <version1> <version2> ... <versionN>

# Sort versions from a file (one per line, # comments, blank lines ignored)
versions sort --from-file <path>
versions sort --desc --from-file <path>

# Alias for string sorting
versions sort-strings <version1> <version2> ... <versionN>
versions sort-strings --desc <version1> <version2> ...

Examples:

versions sort 1.0.0 1.10.0 1.2.0 2.0.0
# Output: 1.0.0 1.2.0 1.10.0 2.0.0

versions sort --desc 1.0.0 1.10.0 1.2.0 2.0.0
# Output: 2.0.0 1.10.0 1.2.0 1.0.0

versions sort --from-file releases.txt

MCP Tools

Tool	Arguments	Returns
version_sort	versions: string[], descending?: bool	{sorted_versions: string[]}
version_min	versions: string[]	oldest version
version_max	versions: string[]	newest version

Cross-References

• [[version-comparison]] — for the underlying CompareTo logic used by sorting
• [[version-parsing]] — for parsing version strings before sorting
• [[version-grouping]] — for grouping versions before sorting groups
• [[version-range-query]] — for querying sorted ranges

Important Notes

• SortVersionStringSlice and SortVersionSlice do NOT modify the original input — they return new slices
• SortVersionGroupSlice DOES modify the input slice in-place — unlike the other sort functions
• VersionSlice implements sort.Interface — use sort.Sort() directly, no closures needed
• "1.10.0" correctly sorts after "1.2.0" — numeric comparison, not alphabetical
• Pre-release versions sort before their release counterparts: "1.0.0-beta" < "1.0.0"
• CLI --from-file reads one version per line, ignores blank lines and # comments
• MCP descending defaults to false (ascending order)