Use git-semver
to generate a valid sematic version on any commit based on the distance to the last tagged version.
|
O - v1.2.1 <-------- git-semver (A) = 1.2.1
| \
* |
| * <-------------- git-semver (B) = 1.2.1-feature-two.2
* |
| *
* | feature/two
| /
* <----------------- git-semver (B) = 1.2.1-main.1
|
O - v1.2.0
|
* main
The git-semver
utility starts with the the closest semver
tag before the requested commit. If the commit is the same as the tag commit, that version is returned (see ex. A
above). If the requested commit is not the same as the tag commit, git-semver
returns the next patch version with a prerelease identifier. The prerelease identifier will be the branch followed by the commit distance to the tag version sanitized for semver (see ex. B
above).
Unlike other libraries this git-semver
uses the Github API (octokit.js) and does not require downloading the entire commit history. Downloading the entire commit history can be burdensome for large repos, This library is perfect for use in CB/CI where detached HEADs are downloaded by default.
NOTE: This provides and MVP version of this utility, but still in initial development for experimentation
example
$ GITHUB_TOKEN=... npx @robpc/git-semver robpc/config 24cbac1
2.0.5-main.4
Requires a GitHub token in the env var GITHUB_TOKEN
.
$ npx @robpc/git-semver --help
Usage: [options] <repository> <reference>
Arguments:
repository github repository as <owner>/<name>
reference commit reference to version
Options:
-i, --increment <increment> version increment size
(choices: "none", "patch", "minor", "major", default: "patch")
-b, --branch-filters <filter...> list of branch filters in priority order
-t, --tag-filters <filter...> list of tag filters in priority order
-s, --add-build-sha add git sha to the build metadata
-d, --add-build-date [date-format] add date to the build metadata, defaults to 'YYYYMMDD-HHmmss' if
no format is supplied
--branch-sort <sort> sort method within branch filters
(choices: "asc", "desc", "semver", default: "desc")
--tag-sort <sort> sort method within tag filters
(choices: "asc", "desc", "semver", default: "semver")
-h, --help display help for command
When a version is found, the version will be incremented to the next patch version, use the -i, --increment
option to choose none
, patch
, minor
, or major
instead.
example
$ GITHUB_TOKEN=... npx @robpc/git-semver robpc/config 24cbac1 -i major
3.0.0-main.4
In semver, the build metadata is useful for adding info about the build but does not affect the version.
Use -s, --add-build-sha
to add the short hash to the build metadata.
example
$ GITHUB_TOKEN=... npx @robpc/git-semver robpc/config 24cbac1 -g
2.0.5-main.4+24cbac1
Use -d, --add-build-date [format]
option to add a date string to the build metadata. If the option is used, but no format is supplied, the default format of YYYYMMDD-HHmmss
will be used. The format string can be anything valid for the dayjs library format
function used to format the date. Note: To maintain semver compatibility, only use [0-9a-zA-Z-]
characters per the semver documentation.
examples
$ GITHUB_TOKEN=... npx @robpc/git-semver robpc/config 24cbac1 -d
2.0.5-main.4+20220118-210623
$ GITHUB_TOKEN=... npx @robpc/git-semver robpc/config 24cbac1 -d 'YYYY-MM-DD.HHmma'
2.0.5-main.4+2022-01-18.2106pm
Branches are searched in the order below by default:
(main|master)
release-.*
hotfix-.*
dev(elop)?
.*
Use -b, --branch-filters
options to supply a custom ordered list of filters. git-semver
will look for branch that has the reference as a ancestor in the order dictated by the filter list. This is useful in situtation where a commit is the ancestor of multiple branches (ie after a merge). In that case, one can prioritize the main
branch over a feature branch. When multiple branches match a filter they will be done in reverse alphabetical order.
Use the --branch-sort
option to provide and alternative method for sorting branches that match a particular filter. The default is desc
which sorts reverse alphabetically, but the options are asc
, desc
, and semver
.
Tags are searched in the order below by default:
v?\\d+(\\.\\d+)?(\\.\\d+)?(-.*)?
.*
Use -t, --tag-filters
options to supply a custom ordered list of filters. git-semver
will look for a tag that is the ancestor of the reference in the order dictated by the filter list. When multiple tags match a filter they will be done in semver order.
Use the --tag-sort
option to provide and alternative method for sorting tags that match a particular filter. The default is semver
which sorts according to sever rules, but the options are asc
, desc
, and semver
.
The command line can be used in a typical Github Action setup. Notice the example below does not include fetch-depth: 0
in the checkout action, which are required by some git utilities. Running this as a step in Github actions can take as little as five seconds.
name: Build
on:
push:
jobs:
build:
name: Build the app
steps:
- name: Check out repository
uses: actions/checkout@v2
- name: Set git-semver version
run: echo "version=$(npx @robpc/git-semver@0.1.6 ${REPO} ${REF})" >> $GITHUB_ENV
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPO: ${{ github.repository }}
REF: ${{ github.sha }}
# Use later in context `${{ env.version }}` or the shell `${version}` like:
# - run: docker -t myapp:${version} build .
# ...
NOTE: More options are available using this as a library, but needs more documentation. See the example below.
import gitSemver from "@robpc/git-semver";
// ...
const token = process.env.GITHUB_TOKEN;
const branches: BranchOptions[] = [
{ filter: "(main|master)", prerelease: "rc", increment: "minor" },
{ filter: "hotfix-.*", sort: "asc", increment: "patch" },
{ filter: "dev(elop)?", prerelease: "beta" },
{ filter: ".*" },
];
const version = await gitSemver(token, owner, repo, ref, {
branches,
});