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.

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

How It Works

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], falling back to the last git tag.
2. bump the version in bumpFiles[1] 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] and updated CHANGELOG.
5. Creates a new tag with the new version number.

bumpFiles, packageFiles and updaters

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!

Maven Support (Java/Kotlin)

If you are using Maven, then just point to your pom.xml file.

commit-and-tag-version --packageFiles pom.xml --bumpFiles pom.xml

Gradle Support (Java/Kotlin)

If you are using Gradle, then just point to your build.gradle file (or build.gradle.kts if using Kotlin DSL).

commit-and-tag-version --packageFiles build.gradle --bumpFiles build.gradle

.NET Support

If you are using .NET with .csproj files. This is going to read and update only the <Version> tag in the file.

commit-and-tag-version --packageFiles <YOUR-PROJECT-NAME>.csproj --bumpFiles <YOUR-PROJECT-NAME>.csproj

YAML Support

If you are using YAML files. This is going to read and update only the version: tag in the file.

commit-and-tag-version --packageFiles file.yaml --bumpFiles file.yaml

OpenAPI Support

If you are using OpenAPI, then just point to your openapi.yaml file.

commit-and-tag-version --packageFiles openapi.yaml --bumpFiles openapi.yaml

Python Support

If you are using Python with Poetry, then point to your pyproject.toml file.

commit-and-tag-version --packageFiles pyproject.toml --bumpFiles pyproject.toml

Installing commit-and-tag-version

As a local npm run script

Install and add to devDependencies:

npm i --save-dev commit-and-tag-version

Add an npm run script to your package.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.

As global bin

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.

Using npx

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.

Configuration

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.

1. Creating a .versionrc, .versionrc.json or .versionrc.js.

2. 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.

Customizing CHANGELOG Generation

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.

Deeper customization

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:

{
  "commit-and-tag-version": {
    "writerOpts": {
      "commitsSort": false
    }
  }
}

CLI Usage

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.

First Release

To generate your changelog for your first release, simply do:

# npm run script
npm run release -- --first-release
# global bin
commit-and-tag-version --first-release
# npx
npx commit-and-tag-version --first-release

This will tag a release without bumping the version bumpFiles1.

When you are ready, push the git tag and npm publish your first release. \o/

Cutting Releases

If you typically use npm version to cut a new release, do this instead:

# npm run script
npm run release
# or 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.

Release as a Pre-Release

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:

# 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 <name>.

For example, suppose your pre-release should contain the alpha prefix:

# 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:

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.

Release as a Target Type Imperatively (npm version-like)

To forgo the automated version bump use --release-as with the argument major, minor or patch.

Suppose the last version of