About The Project

A technology agnostic cli for common semantic versioning operations.

Built with Deno 🦕

Installation

Binaries can be found in the Releases section. Get the latest or install from a supported package manager below.

Installing from binaries or package manager does not require the Deno runtime to also be installed.

Homebrew

brew install optum/tap/semver

via optum

From Source

Installation from source will require Deno to be installed.

module

deno install -gfA https://deno.land/x/semver_cli@0.9.13/main.ts -n semver

git

git clone https://github.com/optum/semver-cli.git
cd semver-cli
deno task install

Usage

semver <command>

Commands:
  semver get            Get the version
  semver set <current>  Set the version
  semver inc            Increment the version
  semver parse [value]  Parse the version

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

About

The get, set and inc commands operate against your working directory. They all operate against a VERSION file found in the root folder of your project.

If the VERSION file is not found the default version is 0.1.0. The inc command will create the VERSION file if it doesn't already exist.

The parse command accepts a version string as input and parses and prints that version as output if it is valid.

examples

# No VERSION file
semver get # 0.1.0

# Sets the VERSION file to 1.2.3 specifically
semver set 1.2.3  # 1.2.3

# Gets the version and increments it, but does not update the VERSION file
semver get minor # 1.3.0
semver get # 1.2.3

# parses a version string
semver parse 1.0.0 # {"major":1,"minor":1,"patch":0,"prerelease":[],"build":[]}

Incrementing

When calling the command inc the VERSION file will be updated based on the sub command specified, major, minor, patch, none. Additional metadata may be added to the version using the --prerelease and --build parameters.

none can be used to synchronize new or out of sync files with post hooks, and also it can be used in conjunction with --prerelease and --build without incrementing the main version numbers.

examples

semver set 1.2.3
semver inc none  # 1.2.3
semver inc patch # 1.2.4
semver inc minor # 1.3.0
semver inc major # 2.0.0

semver set 1.2.3-pre.0
semver inc --prerelease alpha # 1.2.3-alpha.0
semver inc --prerelease alpha # 1.2.3-alpha.1
semver inc --build 1          # 1.2.3-alpha.1+1
semver inc --prerelease beta  # 1.2.3-beta.0+1

Increment Post Hooks

In addition to updating the VERSION file, semver can optionally update source code files in your project. To configure the version command you can provide a configuration file at .github/version.yml.

There are a number of supported post hook kinds and a number of supported known project kinds which make updating source code files easy.

post hook kind

kind	description
replace	replaced the previous version string with the next version string in a file
patch	supports auto-updating a set of well known file types (e.g. package.json)
regexp	replaces matching string using a regexp

patch file kinds

file kind	description
.csproj	Updates the <PropertyGroup><Version>0.1.0</Version></PropertyGroup> element
package.json	Updates the "version": "0.1.0" of the package.json and package-lock.json
Chart.yaml	Updates the version: 0.1.0 of the chart file
pom.xml	Updates the <project><version>0.1.0</version></project> element

If you would like another well known file type supported please file an issue or contribute a pull request. The replace or regexp post hook kinds are flexible in the meantime.

example

on:
  post:
    # Updates both package.json and package-lock.json
    - kind: patch
      file: package.json

    # Uses non-matching groups to isolate the version to replace.
    - kind: regexp
      file: src/info.js
      pattern: '^(?<=export const version = ").*(?=";)$'

Actions

This repository has two actions available, either a basic setup action or a single docker based action.

example

name: Publish
on:
  workflow_dispatch:
    inputs:
      pre:
        type: boolean
        default: true
  release:
    types: [published]

jobs:
  publish:
    steps:
      - if: inputs.pre
        name: Increment Pre-Release Version
        uses: optum/semver-cli@1.0.0-beta.0
        with:
          action: inc
          pre: true
          name: pr
          value: ${{ github.run_number }}
          build: ${{ github.run_id }}

      - id: version
        name: Get Version
        uses: optum/semver-cli@1.0.0-beta.0

      - run: echo "The calculated ${{ steps.version.outputs.version }}"

example of setup action

name: Publish
on:
  release:
    types: [published]

jobs:
  publish:
    steps:
      - name: Increment Pre-Release Version
        uses: optum/semver-cli/setup@0.9.20

      - id: version
        name: Parse Version
        run: |
          echo "version=$(semver parse | jq -r '.version')" > $GITHUB_OUTPUT
          echo "major=$(semver parse | jq -r '.major')" > $GITHUB_OUTPUT
          echo "minor=$(semver parse | jq -r '.minor')" > $GITHUB_OUTPUT
          echo "patch=$(semver parse | jq -r '.patch')" > $GITHUB_OUTPUT

      - run: echo "The calculated ${{ steps.version.outputs.version }}"

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Maintainers

• Justin Chase
  • GitHub Enterprise: justinmchase
  • Email: justin.chase@optum.com