Version File Operations

Version File Operations

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

• Reading version numbers from a text file (one per line)
• Writing a sorted version list to a file
• Processing version lists from dependency lock files or release logs
• Using file-based version data as input for sorting, grouping, or filtering
• Building CI/CD tools that read or write version files

Decision Tree

Need to read and parse versions from a file?
  → Use ReadVersionsFromFile / version_read_file
Need raw strings without parsing overhead?
  → Use ReadVersionsStringFromFile / version_read_file with parse=false
Need to read from a non-file source (HTTP, pipe)?
  → Use ReadVersionsFromReader
Need to write versions to a file sorted?
  → Use WriteVersionsToFile / version_write_file
Need file input for another operation (sort, group, filter)?
  → Use --from-file flag (CLI) or read-then-operate (SDK)

Task Patterns

Read and parse versions from a file

Goal: Load a file, parse each line as a Version, and filter out invalid entries.

Read raw strings without parsing

Goal: Get version strings from a file without the overhead of parsing into Version objects.

Write sorted versions to a file

Goal: Take a list of versions, sort them, and write to a file.

Read from any io.Reader (streaming)

Goal: Parse versions from a non-file source like an HTTP response or string buffer.

Use file input for other operations

Goal: Feed a file's contents directly into sort, group, or range commands.

Full read-filter-write pipeline

Goal: Read versions from a file, filter out invalid ones, and write back sorted.

API Reference

SDK Functions

// Read and parse versions from a file (uses NewVersion, invalid → IsValid()==false)
func ReadVersionsFromFile(filepath string) ([]*Version, error)

// Read raw strings from a file (no parsing overhead)
func ReadVersionsStringFromFile(filepath string) ([]string, error)

// Read and parse versions from any io.Reader (streaming)
func ReadVersionsFromReader(reader io.Reader) ([]*Version, error)

// Write sorted versions to a file (sorts before writing, perm 0644)
func WriteVersionsToFile(versions []*Version, filepath string) error

File Format

# Comments start with # and are ignored
1.0.0
1.0.1

# Blank lines are also ignored
1.1.0-beta
1.1.0

CLI Commands

versions read <filepath>                  # read and parse, display each version
versions read-strings <filepath>          # read raw strings, no parsing
versions write --output <filepath> <v...> # write sorted versions to file

--from-file flag is available on: sort, sort-strings, group, range.

MCP Tools

Cross-References

• [[version-sorting]] — sort versions after reading from a file
• [[version-grouping]] — group versions loaded from a file
• [[version-filtering]] — filter versions read from a file
• [[version-visualization]] — visualize versions loaded from a file

Important Notes

• File format: one version per line; # comments; blank lines ignored; leading/trailing whitespace trimmed.
• ReadVersionsFromFile uses NewVersion (not NewVersionE) — invalid lines become Version objects with IsValid() == false. Always check validity after reading.
• WriteVersionsToFile sorts before writing — the output file is always in ascending order.
• WriteVersionsToFile uses os.WriteFile with permission 0644.
• For very large files, consider streaming with ReadVersionsFromReader instead of ReadVersionsFromFile (which reads the entire file into memory).
• CLI --from-file flag is available on sort, sort-strings, group, and range commands.
• MCP version_read_file supports both parsed and raw output via the parse boolean parameter.
• MCP file tools operate on the server's local filesystem, not the client's.