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 yourPATH
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 yourPATH
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 theminor
andpatch
values to0
.- Setting the
minor
value will only reset thepatch
value to0
- Setting the the
major
,minor
orpatch
value will also clear thepre-release
andbuild
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 theminor
andpatch
values to0
- Incrementing the
minor
value will only reset thepatch
value to0
- Incrementing the
major
,minor
orpatch
value will also clear thepre-release
andbuild
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.