versions

versions is a tool for working with (SemVer) versions on the command-line.

Supported operations:

• Compare versions
• Sort versions
• Select versions given a constraint
• Fetch versions from Git tags
• Fetch versions from Docker image tags
• Dependency version selection using MVS

Contents

• Contents
• Get it
• Use it
  • Compare versions
  • Sort versions
  • Select versions
  • Solve constraint graphs
  • Fetch versions
  • JSON output
  • Sort order
  • Shell completion
• Licensing
• Comments

Get it

Using go get:

go get -u github.com/sgreben/versions/cmd/versions

Or download the binary from the releases page.

# Linux
curl -L https://github.com/sgreben/versions/releases/download/1.1.6/versions_1.1.6_linux_x86_64.tar.gz | tar xz

# OS X
curl -L https://github.com/sgreben/versions/releases/download/1.1.6/versions_1.1.6_osx_x86_64.tar.gz | tar xz

# Windows
curl -LO https://github.com/sgreben/versions/releases/download/1.1.6/versions_1.1.6_windows_x86_64.zip
unzip versions_1.1.6_windows_x86_64.zip

Also available as a docker image:

docker run quay.io/sergey_grebenshchikov/versions

Use it

Usage: versions COMMAND [arg...]

do things with versions

Options:
      --indent   Set the indentation of JSON output (default 0)
  -q, --quiet    Disable all log output (stderr)
  -s, --silent   Disable all log output (stderr) and all normal output (stdout)

Commands:
  sort         Sort versions
  compare      Compare versions
  fetch        Fetch versions
  select       Select versions given constraints
  complete     Shell completion (zsh, fish, bash)
  help         Display help for a command

Run 'versions COMMAND --help' for more information on a command.

Compare versions

Usage: versions compare [OPTIONS] COMMAND [arg...]

Compare versions

Options:
      --fail   Exit with non-zero code if the result is 'false'

Commands:
  later        Check if a version is strictly later than another version
  earlier      Check if a version is strictly earlier than another version

Run 'versions compare COMMAND --help' for more information on a command.

Output a single boolean indicating whether one version is later than another

$ versions compare later 1.0.0 0.1.0

true

$ versions compare later 1.0.0 2.1.0

false

Sort versions

Usage: versions sort [OPTIONS] [VERSIONS...]

Sort versions

Arguments:
  VERSIONS       Versions to sort

Options:
  -l, --latest   Print only the latest `N` versions (default 0)

Print versions in oldest-to-newest order

$ versions sort 2.0.0 0.1.0 10.0.0

["0.1.0","2.0.0","10.0.0"]

Print the latest N versions in oldest-to-newest order

$ versions --latest=2 sort 2.0.0 0.1.0 10.0.0

["2.0.0","10.0.0"]

Select versions

Usage: versions select [OPTIONS] COMMAND [arg...]

Select versions given constraints

Options:
      --from-git      Fetch candidate versions from Git tags
      --from-docker   Fetch candidate versions from Docker tags

Commands:
  single              Select a single version
  all                 Select all matching versions
  mvs                 Select versions to satisfy a constraint graph using MVS (https://research.swtch.com/vgo-mvs)

Run 'versions select COMMAND --help' for more information on a command.

Select the single latest version satisfying the given constraint

$ versions select single '2.*.*' 2.0.0 2.0.1 0.1.0 10.0.0

"2.0.1"

$ versions select single '*' 2.0.0 2.0.1 0.1.0 10.0.0

"10.0.0"

$ versions select single '^0.0.1' 2.0.0 2.0.1 0.1.0 10.0.0

"0.1.0"

Select all versions satisfying the given constraint

$ versions select all '2.*.*' 2.0.0 2.0.1 0.1.0 10.0.0

["2.0.0", "2.0.1"]

Select the single latest version from Git tags satisfying the given constraint

$ versions select --from-git=https://github.com/sgreben/jp single '~1.0.0'

"1.0.1"

$ versions select --from-git=https://github.com/sgreben/jp single '^1.0.0'

"1.1.11"

Select the single latest version from Docker tags satisfying the given constraint

$ versions select --from-docker=alpine single '<3.7'

"3.6.0"

$ versions select --from-docker=alpine single '^3.0.0'

"3.7.0"

Solve constraint graphs

Usage: versions select mvs CONSTRAINTS...

Select versions to satisfy a constraint graph using MVS (https://research.swtch.com/vgo-mvs)

Arguments:
  CONSTRAINTS   constraint graph (JSON structure: {"my-package":{"1.0": {"other-package":"~0.0.1"}}})

Select a set of versions using MVS

Minimal version selection always selects the minimal (oldest) module version that satisfies the overall requirements of a build.

Consider the three packages A, B, and C, where

• A is "our" package
• B has versions 1.0.0 and 2.0.0
• C also has versions 1.0.0 and 2.0.0

A depends on both B and C, and each version of B depends on the same version of C.

If A does not explicitly demand B version 2.0.0, MVS will select 1.0.0 for both dependencies.

$ versions select mvs '{
    "A": {"*": {"B":">=1.0.0", "C":"~1.0.0"}},
    "B": {
        "1.0.0": {"C":"1.*.*"},
        "2.0.0": {"C":"2.*.*"}
    },
    "C": {
        "1.0.0":{},
        "2.0.0":{}
    }
}'

{"Selected":{"B":"1.0.0","C":"1.0.0"},"Relaxed":{}}

On the other hand, if A does explicitly demand B >= 2.0.0, MVS will upgrade B to 2.0.0, but also have to upgrade C to 2.0.0 due to B's constraint. MVS does not support "maximum versions", thus the constraint C~1.0.0 of A must be relaxed to obtain a solution:

$ versions select mvs '{
    "A": {"*": {"B":">=2.0.0", "C":"~1.0.0"}},
    "B": {
        "1.0.0": {"C":"1.*.*"},
        "2.0.0": {"C":"2.*.*"}
    },
    "C": {
        "1.0.0":{},
        "2.0.0":{}
    }
}'

{"Selected":{"B":"2.0.0","C":"2.0.0"},"Relaxed":{"A":{"C":"~1.0.0"}}}

The constraints can also be provided via multiple JSON arguments:

versions select mvs \
  '{"A": {"*": {"B":">=2.0.0", "C":"~1.0.0"}}}' \
  '{"B": {"1.0.0": {"C":"1.*.*"}, "2.0.0": {"C":"2.*.*"}}}' \
  '{"C": {"1.0.0":{}, "2.0.0":{}}}'

{"Selected":{"B":"2.0.0","C":"2.0.0"},"Relaxed":{"A":{"C":"~1.0.0"}}}

Fetch versions

Usage: versions fetch [OPTIONS] COMMAND [arg...]

Fetch versions

Options:
  -l, --latest   Print only the latest `N` versions (default 0)

Commands:
  git            Fetch versions from Git tags
  docker         Fetch versions from Docker image tags

Run 'versions fetch COMMAND --help' for more information on a command.

Fetch and interpret all SemVer git tags as versions

$ versions --indent=2 fetch git https://github.com/sgreben/jp

[
  {
    "Version": "1.0.0",
    "Source": {
      "Git": {
        "Repository": {
          "URL": "https://github.com/sgreben/jp"
        },
        "Reference": "refs/tags/1.0.0"
      }
    }
  },
  {
    "Version": "1.0.1",
    "Source": {
      "Git": {
        "Repository": {
          "URL": "https://github.com/sgreben/jp"
        },
        "Reference": "refs/tags/1.0.1"
  // ...
]

Fetch and determine the latest version from Git tags

$ versions fetch -l 1 git https://github.com/sgreben/jp

[{"Version":"1.1.11","Source":{"Git":{"Repository":{"URL":"https://github.com/sgreben/jp"},"Reference":"refs/tags/1.1.11"}}}]

Fetch and interpret all Docker image tags as versions

$ versions --indent=2 fetch docker alpine

[
  {
    "Version": "2.6.0",
    "Source": {
      "Docker": {
        "Image": "library/alpine:2.6",
        "Tag": "2.6"
      }
    }
  },
  {
    "Version": "2.7.0",
    "Source": {
      "Docker": {
        "Image": "library/alpine:2.7",
        "Tag": "2.7"
      }
    }
  },
  // ...
]

Fetch and determine the latest version from Docker image tags

$ versions fetch -l 1 docker alpine

[{"Version":"3.7.0","Source":{"Docker":{"Image":"library/alpine:3.7","Tag":"3.7"}}}]

JSON output

The default output format is JSON, one value per line:

$ versions sort 0.10 0.2 1.0 1.1 1.1.1-rc1 1.1.1

["0.2.0","0.10.0","1.0.0","1.1.0","1.1.1-rc1","1.1.1"]

To output multi-line indented JSON, specify a value for the --indent option:

$ versions --indent=2 sort 0.10 0.2 1.0 1.1 1.1.1-rc1 1.1.1

[
  "0.2.0",
  "0.10.0",
  "1.0.0",
  "1.1.0",
  "1.1.1-rc1",
  "1.1.1"
]

Sort order

All commands that produce sorted lists of versions produce them in the oldest-first, latest-last order:

$ versions sort 0.0.1 1.0.0

["0.0.1","1.0.0"]

Shell completion

The tool can install shell (zsh, fish, bash) completion for itself:

Usage: versions complete COMMAND [arg...]

Shell completion (zsh, fish, bash)

Commands:
  install      Install all completions
  uninstall    Uninstall all completions

Run 'versions complete COMMAND --help' for more information on a command.

$ versions complete install
$ tail -n1 ~/.zshrc
complete -o nospace -C /go/bin/versions versions

$ versions <TAB>
compare  fetch    help     select   sort

$ versions select -<TAB>
--from-docker  --from-git     --help         -h

Licensing

• Any original code is licensed under the MIT License.
• The included version of github.com/Masterminds/semver is licensed under what looks like the MIT license.
• Included portions of github.com/kubernetes/client-go are licensed under the Apache License 2.0.

Comments

Feel free to leave a comment or create an issue.