replacement for `npm version` with automatic CHANGELOG generation
npm install commit-and-tag-version> commit-and-tag-version is a fork of standard-version. Because of maintainer availability, standard-version was deprecated on 15th May 2022. The previous maintainer recommends release-please as an alternative for those who are using GitHub actions. This fork exists for those who can't switch to release-please, or who would like to continue using standard-version.
> Can I simply swap the library to migrate? To migrate, you can drop in commit-and-tag-version in place of standard-version. There are no changes in 9.5.0, other than to add the package.json config key commit-and-tag-version (the previous configuration key standard-version will still work). 10.x drops support for deprecated node versions, 11.x is a formatting change if you're relying on the exact markdown format in the changelog, and 12.x drops support for node 14/16.
> Why was it renamed commit-and-tag-version?. I didn't want to scope the package or name it standard-version-fork, and it was a good opportunity to make the purpose of the tool clearer. I also wanted to distinguish it from the other tool in this organisation, absolute-version, which just prints version information for pre-releases.
A utility for versioning using semver and CHANGELOG generation powered by Conventional Commits.
!ci
_Having problems? Want to contribute? Join us on the node-tooling community Slack_.
- Commit and Tag Version
- How It Works:
- bumpFiles, packageFiles and updaters
- Maven Support (Java/Kotlin)
- Gradle Support (Java/Kotlin)
- .NET Support
- YAML Support
- OpenAPI Support
- Python Support
- Installing commit-and-tag-version
- As a local npm run script
- As global bin
- Using npx
- Configuration
- Customizing CHANGELOG Generation
- Deeper customization
- CLI Usage
- First Release
- Cutting Releases
- Release as a Pre-Release
- Release as a Target Type Imperatively (npm version-like)
- Prevent Git Hooks
- Custom Config Path
- Signing Commits and Tags
- Lifecycle Scripts
- Skipping Lifecycle Steps
- Committing Generated Artifacts in the Release Commit
- Dry Run Mode
- Prefix Tags
- Tag replacement
- Generate changelogs for old releases
- CLI Help
- Code Usage
- FAQ
- How is commit-and-tag-version different from semantic-release?
- Should I always squash commits when merging PRs?
- Can I use commit-and-tag-version for additional metadata files, languages or version files?
- Custom updaters
- readVersion(contents = string): string
- writeVersion(contents = string, version: string): string
- License
1. Follow the Conventional Commits Specification in your repository.
2. When you're ready to release, run commit-and-tag-version.
commit-and-tag-version will then do the following:
1. Retrieve the current version of your repository by looking at packageFiles[[1]](#bumpfiles-packagefiles-and-updaters), falling back to the last git tag.
2. bump the version in bumpFiles[[1]](#bumpfiles-packagefiles-and-updaters) based on your commits.
3. Generates a changelog based on your commits (uses conventional-changelog under the hood).
4. Creates a new commit including your bumpFiles[[1]](#bumpfiles-packagefiles-and-updaters) and updated CHANGELOG.
5. Creates a new tag with the new version number.
commit-and-tag-version uses a few key concepts for handling version bumping in your project.
- packageFiles – User-defined files where versions can be read from _and_ be "bumped".
- Examples: package.json, manifest.json
- In most cases (including the default), packageFiles are a subset of bumpFiles.
- bumpFiles – User-defined files where versions should be "bumped", but not explicitly read from.
- Examples: package-lock.json, npm-shrinkwrap.json
- updaters – Simple modules used for reading packageFiles and writing to bumpFiles.
By default, commit-and-tag-version assumes you're working in a NodeJS based project... because of this, for the majority of projects you might never need to interact with these options.
That said, if you find your self asking How can I use commit-and-tag-version for additional metadata files, languages or version files? – these configuration options will help!
If you are using Maven, then just point to your pom.xml file.
``sh`
commit-and-tag-version --packageFiles pom.xml --bumpFiles pom.xml
If you are using Gradle, then just point to your build.gradle file (or build.gradle.kts if using Kotlin DSL).
`sh`
commit-and-tag-version --packageFiles build.gradle --bumpFiles build.gradle
If you are using .NET with .csproj files.
This is going to read and update only the tag in the file.
`sh`
commit-and-tag-version --packageFiles
If you are using YAML files.
This is going to read and update only the version: tag in the file.
`sh`
commit-and-tag-version --packageFiles file.yaml --bumpFiles file.yaml
If you are using OpenAPI, then just point to your openapi.yaml file.
`sh`
commit-and-tag-version --packageFiles openapi.yaml --bumpFiles openapi.yaml
If you are using Python with Poetry, then point to your pyproject.toml file.
`sh`
commit-and-tag-version --packageFiles pyproject.toml --bumpFiles pyproject.toml
Install and add to devDependencies:
`
npm i --save-dev commit-and-tag-version
Add an npm run script to your package.json:
`json`
{
"scripts": {
"release": "commit-and-tag-version"
}
}
Now you can use npm run release in place of npm version.
This has the benefit of making your repo/package more portable, so that other developers can cut releases without having to globally install commit-and-tag-version on their machine.
Install globally (add to your PATH):
`
npm i -g commit-and-tag-version
Now you can use commit-and-tag-version in place of npm version.
This has the benefit of allowing you to use commit-and-tag-version on any repo/package without adding a dev dependency to each one.
As of npm@5.2.0, npx is installed alongside npm. Using npx you can use commit-and-tag-version without having to keep a package.json file by running: npx commit-and-tag-version.
This method is especially useful when using commit-and-tag-version in non-JavaScript projects.
You can configure commit-and-tag-version either by:
1. Placing a commit-and-tag-version stanza in your package.json (assuming
your project is JavaScript).
> Note for users who have migrated to
commit-and-tag-version from standard-version: the previous package.json configuration key of standard-version will still work.
2. Creating a .versionrc, .versionrc.json or .versionrc.js.
- If you are using a .versionrc.js your default export must be a configuration object, or a function returning a configuration object.
Any of the command line parameters accepted by commit-and-tag-version can instead
be provided via configuration. Please refer to the conventional-changelog-config-spec for details on available configuration options.
By default, commit-and-tag-version uses the conventionalcommits preset.
This preset adheres closely to the conventionalcommits.org specification.
Suppose you're using GitLab, rather than GitHub, you might modify the following variables:
- commitUrlFormat: the URL format of commit SHAs detected in commit messages.compareUrlFormat
- : the URL format used to compare two tags.issueUrlFormat
- : the URL format used to link to issues.
Making these URLs match GitLab's format, rather than GitHub's.
You can override both parser and writer options (they will be merged into the preset we just mentioned). As an example, to list commits in the order that they were committed:
`json`
{
"commit-and-tag-version": {
"writerOpts": {
"commitsSort": false
}
}
}
> NOTE: To pass nested configurations to the CLI without defining them in the package.json use dot notation as the parameters e.g. --skip.changelog.
To generate your changelog for your first release, simply do:
`sh`npm run script
npm run release -- --first-releaseglobal bin
commit-and-tag-version --first-releasenpx
npx commit-and-tag-version --first-release
This will tag a release without bumping the version bumpFiles[1]().
When you are ready, push the git tag and npm publish your first release. \o/
If you typically use npm version to cut a new release, do this instead:
`sh`npm run script
npm run releaseor global bin
commit-and-tag-version
As long as your git commit messages are conventional and accurate, you no longer need to specify the semver type - and you get CHANGELOG generation for free! \o/
After you cut a release, you can push the new git tag and npm publish (or npm publish --tag next) when you're ready.
Use the flag --prerelease to generate pre-releases:
Suppose the last version of your code is 1.0.0, and your code to be committed has patched changes. Run:
`bash`npm run script
npm run release -- --prerelease
This will tag your version as: 1.0.1-0.
If you want to name the pre-release, you specify the name via --prerelease .
For example, suppose your pre-release should contain the alpha prefix:
`bash`npm run script
npm run release -- --prerelease alpha
This will tag the version as: 1.0.1-alpha.0
#### Prerelease Tag Collision Avoidance
When cutting a prerelease with --prerelease, commit-and-tag-version automatically checks existing git tags (respecting your tagPrefix configuration) for the same base version and prerelease channel. If a tag already exists, the numeric suffix is automatically incremented to avoid conflicts.
For example, if you're working with multiple prerelease channels simultaneously:
`bash`
commit-and-tag-version --prerelease xyz # Creates v1.4.3-xyz.0
commit-and-tag-version --prerelease abc # Creates v1.4.3-abc.0
commit-and-tag-version --prerelease xyz # Creates v1.4.3-xyz.1 (auto-incremented)
This behavior applies to both named prereleases (e.g., -alpha.0, -beta.1) and unnamed prereleases (e.g., -0, -1), ensuring that you can safely cut multiple prerelease versions without encountering git tag conflicts.
To forgo the automated version bump use --release-as with the argument major, minor or patch.
Suppose the last version of your code is 1.0.0, you've only landed fix: commits, butminor
you would like your next release to be a . Simply run the following:
`bash`npm run script
npm run release -- --release-as minorOr
npm run release -- --release-as 1.1.0
You will get version 1.1.0 rather than what would be the auto-generated version 1.0.1.
> NOTE: you can combine --release-as and --prerelease to generate a release. This is useful when publishing experimental feature(s).
If you use git hooks, like pre-commit, to test your code before committing, you can prevent hooks from being verified during the commit step by passing the --no-verify option:
`sh`npm run script
npm run release -- --no-verifyor global bin
commit-and-tag-version --no-verify
Specify a custom path to the configuration file using the --config option
`sh
commit-and-tag-version --config ./path/to/.versionrc.js
All config file formats can be used:
sh
commit-and-tag-version -c ./path/to/.versionrc[.js|.cjs|.json]
`$3
If you have your GPG key set up, add the
or -s flag to your commit-and-tag-version command.$3
To add the "Signed-off-by" trailer to the commit message add the
--signoff flag to your commit-and-tag-version command.$3
commit-and-tag-version supports lifecycle scripts. These allow you to execute your
own supplementary commands during the release. The following
hooks are available and execute in the order documented:-
prerelease: executed before anything happens. If the prerelease script returns a
non-zero exit code, versioning will be aborted, but it has no other effect on the
process.
- prebump/postbump: executed before and after the version is bumped. If the prebump
script returns a version #, it will be used rather than
the version calculated by .
- prechangelog/postchangelog: executes before and after the CHANGELOG is generated.
- precommit/postcommit: called before and after the commit step.
- pretag/posttag: called before and after the tagging step.Simply add the following to your package.json to configure lifecycle scripts:
`json
{
"commit-and-tag-version": {
"scripts": {
"prebump": "echo 9.9.9"
}
}
}
`As an example to change from using GitHub to track your items to using your projects Jira use a
script to replace the url fragment containing 'myproject/issues/>'
with a link to your Jira - assuming you have already installed replace`json
{
"commit-and-tag-version": {
"scripts": {
"postchangelog": "replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md"
}
}
}
`$3
You can skip any of the lifecycle steps (
, changelog, commit, tag),
by adding the following to your package.json:`json
{
"commit-and-tag-version": {
"skip": {
"changelog": true
}
}
}
`$3
If you want to commit generated artifacts in the release commit, you can use the
or -a flag. You will need to stage the artifacts you want to commit, so your release command could look like this:`json
{
"commit-and-tag-version": {
"scripts": {
"prerelease": "webpack -p --bail && git add "
}
}
}
`json
{
"scripts": {
"release": "commit-and-tag-version -a"
}
}
`$3
running
with the flag --dry-run allows you to see what
commands would be run, without committing to git or updating files.`sh
npm run script
npm run release -- --dry-run
or global bin
commit-and-tag-version --dry-run
`$3
Tags are prefixed with
by default. If you would like to prefix your tags with something else, you can do so with the -t flag.`sh
commit-and-tag-version -t @scope/package\@
`This will prefix your tags to look something like
If you do not want to have any tag prefix you can use the
flag and provide it with an empty string as value.> Note: simply -t or --tag-prefix without any value will fallback to the default 'v'
$3
If you've already run
commit-and-tag-version when creating your release, you may want to alter the release content and changelog without bumping
the version, by using commit-and-tag-version --skip.bump. By default, tagging with an already existing tag make git fails.
You can add the --tag-force flag to make use of -f option when calling git tag, then the existing version tag will be replaced.$3
Normally only the changelog for the last release will be generated and prepended to the
changelog.md. If you want to generate changelogs for previous releases you can do so by setting the releaseCount option like described here.When setting releaseCount=0 the whole changelog gets regenerated and replaced.
You can set the option either in the
.versionrc file or inside package.json like below`json
//.versionrc
{
"releaseCount": 0
}//package.json
"commit-and-tag-version": {
"releaseCount": 0
}
`$3
sh
npm run script
npm run release -- --help
or global bin
commit-and-tag-version --help
`Code Usage
js
const commitAndTagVersion = require("commit-and-tag-version");// Options are the same as command line, except camelCase
// commitAndTagVersion returns a Promise
commitAndTagVersion({
noVerify: true,
infile: "docs/CHANGELOG.md",
silent: true,
})
.then(() => {
// commit-and-tag-version is done
})
.catch((err) => {
console.error(
commit-and-tag-version failed with message: ${err.message});
});
`_TIP: Use the
option to prevent commit-and-tag-version from printing to the console._FAQ
$3
semantic-release is described as:> semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
While both are based on the same foundation of structured commit messages,
commit-and-tag-version takes a different approach by handling versioning, changelog generation, and git tagging for you without automatic pushing (to GitHub) or publishing (to an npm registry). Use of commit-and-tag-version only affects your local git repo - it doesn't affect remote resources at all. After you run commit-and-tag-version, you can review your release state, correct mistakes and follow the release strategy that makes the most sense for your codebase.We think they are both fantastic tools, and we encourage folks to use
semantic-release instead of commit-and-tag-version if it makes sense for their use-case.$3
The instructions to squash commits when merging pull requests assumes that one PR equals, at most, one feature or fix.
If you have multiple features or fixes landing in a single PR and each commit uses a structured message, then you can do a standard merge when accepting the PR. This will preserve the commit history from your branch after the merge.
Although this will allow each commit to be included as separate entries in your CHANGELOG, the entries will not be able to reference the PR that pulled the changes in because the preserved commit messages do not include the PR number.
For this reason, we recommend keeping the scope of each PR to one general feature or fix. In practice, this allows you to use unstructured commit messages when committing each little change and then squash them into a single commit with a structured message (referencing the PR number) once they have been reviewed and accepted.
$3
You can configure multiple
bumpFiles and packageFiles:1. Specify a custom
bumpFile "filename", this is the path to the file you want to "bump"
2. Specify the bumpFile "updater", this is _how_ the file will be bumped.
a. If you're using a common type, you can use one of commit-and-tag-version's built-in updaters by specifying a type.
b. If your using an less-common version file, you can create your own updater.`js
// .versionrc
{
"bumpFiles": [
{
"filename": "MY_VERSION_TRACKER.txt",
// The plain-text updater assumes the file contents represents the version.
"type": "plain-text"
},
{
"filename": "a/deep/package/dot/json/file/package.json",
// The json updater assumes the version is available under a version key in the provided JSON document.
"type": "json"
},
{
"filename": "VERSION_TRACKER.json",
// See "Custom updaters" for more details.
"updater": "commit-and-tag-version-updater.js"
}
]
}
`If using
as your configuration file, the updater may also be set as an object, rather than a path:`js
// .versionrc.js
const tracker = {
filename: "VERSION_TRACKER.json",
updater: require("./path/to/custom-version-updater"),
};module.exports = {
bumpFiles: [tracker],
packageFiles: [tracker],
};
`#### Custom
sAn
updater is expected to be a Javascript module with _atleast_ two methods exposed: readVersion and writeVersion.#####
readVersion(contents = string): stringThis method is used to read the version from the provided file contents.
The return value is expected to be a semantic version string.
#####
This method is used to write the version to the provided contents.
The return value will be written directly (overwrite) to the provided file.
---
Let's assume our
has the following contents:`json
{
"tracker": {
"package": {
"version": "1.0.0"
}
}
}
`An acceptable
would be:`js
// commit-and-tag-version-updater.js
const stringifyPackage = require("stringify-package");
const detectIndent = require("detect-indent");
const detectNewline = require("detect-newline");module.exports.readVersion = function (contents) {
return JSON.parse(contents).tracker.package.version;
};
module.exports.writeVersion = function (contents, version) {
const json = JSON.parse(contents);
let indent = detectIndent(contents).indent;
let newline = detectNewline(contents);
json.tracker.package.version = version;
return stringifyPackage(json, indent, newline);
};
`$3
Below 1.0.0, the semver specification doesn't give any guarantees about the
meaning of version numbers. However, with npm there is a community convention,
and implementation-defined behaviour: If your version is between 0.1.0 and
1.0.0, npm treats an update to the minor version as a breaking change - that is
^0.1.0 will match 0.1.2 but not 0.2.0. Rust's cargo package manager also behaves
the same way.
This tool (via conventional-commits) also follows that convention - breaking
changes below v1.0.0 are treated as a minor version bump. Here's an example
series of commits with tagged versions:
1017b00 chore: initial commit
9e2ba95 (tag: v0.0.2) chore(release): 0.0.2
3598012 fix!: Example breaking change
1a4994a (tag: v0.1.0) chore(release): 0.1.0
Semver's only guarantee is "all bets are off", but npm has made a choice about
what bets to make.
follows the same convention (along
with other package managers for other ecosystems).When you are ready to release v1.0.0, add
--release-as 1.0.0 to the options.$3
By default, the conventional commits preset is used. This means that only
fix, feat` and anything marked as a breaking change will appear in the changelog.Conventional commits is meant to make it easy for machines to reason about the user-facing changes,
and the changelog generation makes it easy for humans to consume this information too.
Usually, you wouldn't want non-user facing changes like refactor in the changelog.
License
ISC