README

Command line tool for managing semantic versioning for a project
Created by Chris Kankiewicz (@PHLAK)

Requirements

PHP >= 7.2

Installation

The SemVer CLI can be installed via Composer per-project or globally.

Per-project

composer require phlak/semver-cli

When installed to a projcet the semver tool is installed to the project's vendor/bin directory.

ℹ️ It is recommended to add vendor/bin to your PATH environment variable when installing within a project. Otherwise you will have to call the command with a relative path (i.e. vendor/bin/semver [arguments]) every time.

Globally

composer global require phlak/semver-cli

When required globally the semver tool will be installed to the global ${COMOPSER_HOME}/vendor/bin directory.

ℹ️ You should add ${COMOPSER_HOME}/vendor/bin to your PATH environment variable when installing globally. If you don't you will have to specify the full installation path with every call call.

Usage

Initialization

To begin, you must initialize semantic versioning within a directory.

$ semver initialize

This initializes the version to 0.1.0 by creating a VERSION file containing the version in the current directory.

Initialize a Specific Version

To initialize to a specific version, pass the version as an argument to the initialize command.

$ semver initialize 1.3.37

Initializing Incomplete Versions

Sometimes you may need to initialize semantic versioning with an incomplete version. By default the initialize command requires a valid semantic version string. If you want to allow the command to make a "best guess" attempt you can do so with the --parse option.

$ semver initialize --parse 1.2

Setting Version Values

After initialization you can set (override) the complete version with the set:version command.

$ semver set:version 1.3.37

Alternately, you may set individual values.

$ semver set:major 1
$ semver set:minor 3
$ semver set:patch 37
$ semver set:pre-release beta.5
$ semver set:build 007

ℹ️ Setting certain values may affect other values

Setting the major value will reset the minor and patch values to 0.

Setting the minor value will only reset the patch value to 0

Setting the the major, minor or patch value will also clear the pre-release and build values

Clearing Values

You may clear the pre-release or build values with the clear commands.

$ semver clear:build
$ semver clear:pre-release

Retrieving Values

At any point after initialization you may get the full version.

$ semver get:version

To get the version prefixed with v (i.e. v1.3.37) use the --prefix option.

$ semver get:version --prefix

You may also retrieve individual values.

$ semver get:major
$ semver get:minor
$ semver get:patch
$ semver get:pre-release
$ semver get:build

If the pre-release and build values are unset they will return no output by default. To force output add the --verbose option.

$ semver get:pre-release --verbose
$ semver get:build --verbose

Incrementing the Version

You can increment the version values with the increment command.

$ semver increment:major
$ semver increment:minor
$ semver increment:patch

ℹ️ Incrementing certain values may affect other values

Incrementing the major value will reset the minor and patch values to 0

Incrementing the minor value will only reset the patch value to 0

Incrementing the major, minor or patch value will also clear the pre-release and build values

Adapters

The method used for storing version information can be configured with the --adapter option. The following are the available adapters to choose from.

file: Stores the version in a regular file in the current directory (default)
composer: Stores the version in the composer.json file under the version property

When using the file adapter you can control the file to which commands read and write the version via the --file option. This option takes the name you'd like to use and will look for a file with that name in the current directory.

$ semver --file .version get:version

By default the composer adapter will look for your composer.json file in the current directory. If your composer.json file lives elsewhere you can specify the path with the --composer option.

$ semver --composer path/to/composer.json increment:major

ℹ️ Adapter options can be passed passed along with any command.

Configuration

Instead of passing adapter options with every command you can set these options in a persistent configuration file. To enable the config create a file in your project directory with a name of semver.config.php. This file MUST be a PHP file and return an array with with one or more of the followng configuration options.

adapter

The storage adapter in which version data will be stored.

Equivilent to the --adapter option.

file_name

Name of the version file when using the file adapter.

Equvilent to the --file option.

composer_file

Path to the composer file when using the composer adpater

Equvilent to the --composer option.

Examples

<?php

return [
    'adapter' => 'composer',
    'composer_file' => 'some/path/composer.json',
];

Changelog

A list of changes can be found on the GitHub Releases page.

Troubleshooting

For general help and support join our GitHub Discussions or reach out on Twitter.

Please report bugs to the GitHub Issue Tracker.

Copyright

This project is liscensed under the MIT License.

phlak / semver-cli

Maintainers

Details