{"id":13476215,"url":"https://github.com/absolute-version/commit-and-tag-version","last_synced_at":"2026-03-17T07:02:32.870Z","repository":{"id":37429045,"uuid":"496044204","full_name":"absolute-version/commit-and-tag-version","owner":"absolute-version","description":"Fork of the excellent standard-version. Automate versioning and CHANGELOG generation, with semver.org and conventionalcommits.org :trophy:","archived":false,"fork":true,"pushed_at":"2024-11-19T03:41:44.000Z","size":1222,"stargazers_count":423,"open_issues_count":53,"forks_count":40,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-19T04:29:10.003Z","etag":null,"topics":["changelog","cli","git","history","release","semantic","standard","tag","tags","version","versioning"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"conventional-changelog/standard-version","license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/absolute-version.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-05-25T01:38:29.000Z","updated_at":"2024-11-19T03:41:41.000Z","dependencies_parsed_at":"2023-02-10T09:31:47.597Z","dependency_job_id":"b8cd12e0-f9e4-4662-b14d-ce8147b0e08a","html_url":"https://github.com/absolute-version/commit-and-tag-version","commit_stats":{"total_commits":383,"total_committers":91,"mean_commits":4.208791208791209,"dds":0.8172323759791122,"last_synced_commit":"bc6f792bcb72b17d912a17f3927fba3ecf297492"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absolute-version%2Fcommit-and-tag-version","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absolute-version%2Fcommit-and-tag-version/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absolute-version%2Fcommit-and-tag-version/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absolute-version%2Fcommit-and-tag-version/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/absolute-version","download_url":"https://codeload.github.com/absolute-version/commit-and-tag-version/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245769408,"owners_count":20669176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changelog","cli","git","history","release","semantic","standard","tag","tags","version","versioning"],"created_at":"2024-07-31T16:01:27.703Z","updated_at":"2026-03-17T07:02:32.864Z","avatar_url":"https://github.com/absolute-version.png","language":"JavaScript","readme":"# Commit and Tag Version\n\n\u003e **`commit-and-tag-version` is a fork of `standard-version`**. Because of maintainer availability, `standard-version` was [deprecated on 15th May 2022](https://github.com/conventional-changelog/standard-version/pull/907). The previous maintainer recommends [release-please](https://github.com/googleapis/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`.\n\n\u003e **`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.\n\n\u003e **`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`](https://github.com/absolute-version/absolute-version-js), which just prints version information for pre-releases. \n\nA utility for versioning using [semver](https://semver.org/) and CHANGELOG generation powered by [Conventional Commits](https://conventionalcommits.org).\n\n![ci](https://github.com/absolute-version/commit-and-tag-version/workflows/ci/badge.svg)\n[![NPM version](https://img.shields.io/npm/v/commit-and-tag-version.svg)](https://www.npmjs.com/package/commit-and-tag-version)\n[![codecov](https://codecov.io/gh/absolute-version/commit-and-tag-version/branch/master/graph/badge.svg?token=J7zMN7vTTd)](https://codecov.io/gh/absolute-version/commit-and-tag-version)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n[![Community slack](http://devtoolscommunity.herokuapp.com/badge.svg)](http://devtoolscommunity.herokuapp.com)\n\n_Having problems? Want to contribute? Join us on the [node-tooling community Slack](http://devtoolscommunity.herokuapp.com)_.\n\n- [Commit and Tag Version](#commit-and-tag-version)\n    - [How It Works:](#how-it-works)\n    - [`bumpFiles`, `packageFiles` and `updaters`](#bumpfiles-packagefiles-and-updaters)\n    - [Maven Support (Java/Kotlin)](#maven-support-javakotlin)\n    - [Gradle Support (Java/Kotlin)](#gradle-support-javakotlin)\n    - [.NET Support](#net-support)\n    - [YAML Support](#yaml-support)\n    - [OpenAPI Support](#openapi-support)\n    - [Python Support](#python-support)\n  - [Installing `commit-and-tag-version`](#installing-commit-and-tag-version)\n    - [As a local `npm run` script](#as-a-local-npm-run-script)\n    - [As global `bin`](#as-global-bin)\n    - [Using `npx`](#using-npx)\n  - [Configuration](#configuration)\n    - [Customizing CHANGELOG Generation](#customizing-changelog-generation)\n    - [Deeper customization](#deeper-customization)\n  - [CLI Usage](#cli-usage)\n    - [First Release](#first-release)\n    - [Cutting Releases](#cutting-releases)\n    - [Release as a Pre-Release](#release-as-a-pre-release)\n    - [Release as a Target Type Imperatively (`npm version`-like)](#release-as-a-target-type-imperatively-npm-version-like)\n    - [Prevent Git Hooks](#prevent-git-hooks)\n    - [Custom Config Path](#custom-config-path)\n    - [Signing Commits and Tags](#signing-commits-and-tags)\n    - [Lifecycle Scripts](#lifecycle-scripts)\n    - [Skipping Lifecycle Steps](#skipping-lifecycle-steps)\n    - [Committing Generated Artifacts in the Release Commit](#committing-generated-artifacts-in-the-release-commit)\n    - [Dry Run Mode](#dry-run-mode)\n    - [Prefix Tags](#prefix-tags)\n    - [Tag replacement](#tag-replacement)\n    - [Generate changelogs for old releases](#generate-changelogs-for-old-releases)\n    - [CLI Help](#cli-help)\n  - [Code Usage](#code-usage)\n  - [FAQ](#faq)\n    - [How is `commit-and-tag-version` different from `semantic-release`?](#how-is-commit-and-tag-version-different-from-semantic-release)\n    - [Should I always squash commits when merging PRs?](#should-i-always-squash-commits-when-merging-prs)\n    - [Can I use `commit-and-tag-version` for additional metadata files, languages or version files?](#can-i-use-commit-and-tag-version-for-additional-metadata-files-languages-or-version-files)\n      - [Custom `updater`s](#custom-updaters)\n        - [`readVersion(contents = string): string`](#readversioncontents--string-string)\n        - [`writeVersion(contents = string, version: string): string`](#writeversioncontents--string-version-string-string)\n  - [License](#license)\n\n\n### How It Works\n\n1. Follow the [Conventional Commits Specification](https://conventionalcommits.org) in your repository.\n2. When you're ready to release, run `commit-and-tag-version`.\n\n`commit-and-tag-version` will then do the following:\n\n1. Retrieve the current version of your repository by looking at `packageFiles`[[1]](#bumpfiles-packagefiles-and-updaters), falling back to the last `git tag`.\n2. `bump` the version in `bumpFiles`[[1]](#bumpfiles-packagefiles-and-updaters) based on your commits.\n3. Generates a `changelog` based on your commits (uses [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) under the hood).\n4. Creates a new `commit` including your `bumpFiles`[[1]](#bumpfiles-packagefiles-and-updaters) and updated CHANGELOG.\n5. Creates a new `tag` with the new version number.\n\n### `bumpFiles`, `packageFiles` and `updaters`\n\n`commit-and-tag-version` uses a few key concepts for handling version bumping in your project.\n\n- **`packageFiles`** – User-defined files where versions can be read from _and_ be \"bumped\".\n  - Examples: `package.json`, `manifest.json`\n  - In most cases (including the default), `packageFiles` are a subset of `bumpFiles`.\n- **`bumpFiles`** – User-defined files where versions should be \"bumped\", but not explicitly read from.\n  - Examples: `package-lock.json`, `npm-shrinkwrap.json`\n- **`updaters`** – Simple modules used for reading `packageFiles` and writing to `bumpFiles`.\n\nBy 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.\n\nThat said, if you find your self asking [How can I use commit-and-tag-version for additional metadata files, languages or version files?](#can-i-use-commit-and-tag-version-for-additional-metadata-files-languages-or-version-files) – these configuration options will help!\n\n### Maven Support (Java/Kotlin)\n\nIf you are using Maven, then just point to your `pom.xml` file.\n\n```sh\ncommit-and-tag-version --packageFiles pom.xml --bumpFiles pom.xml\n```\n\n### Gradle Support (Java/Kotlin)\n\nIf you are using Gradle, then just point to your `build.gradle` file (or `build.gradle.kts` if using Kotlin DSL).\n\n```sh\ncommit-and-tag-version --packageFiles build.gradle --bumpFiles build.gradle\n```\n\n### .NET Support\n\nIf you are using .NET with `.csproj` files.\nThis is going to read and update only the `\u003cVersion\u003e` tag in the file.\n\n```sh\ncommit-and-tag-version --packageFiles \u003cYOUR-PROJECT-NAME\u003e.csproj --bumpFiles \u003cYOUR-PROJECT-NAME\u003e.csproj\n```\n\n### YAML Support\n\nIf you are using YAML files.\nThis is going to read and update only the `version:` tag in the file.\n\n```sh\ncommit-and-tag-version --packageFiles file.yaml --bumpFiles file.yaml\n```\n\n### OpenAPI Support\n\nIf you are using OpenAPI, then just point to your `openapi.yaml` file.\n\n```sh\ncommit-and-tag-version --packageFiles openapi.yaml --bumpFiles openapi.yaml\n```\n\n### Python Support\n\nIf you are using Python ***with Poetry***, then point to your `pyproject.toml` file.\n\n```sh\ncommit-and-tag-version --packageFiles pyproject.toml --bumpFiles pyproject.toml\n```\n\n## Installing `commit-and-tag-version`\n\n### As a local `npm run` script\n\nInstall and add to `devDependencies`:\n\n```\nnpm i --save-dev commit-and-tag-version\n```\n\nAdd an [`npm run` script](https://docs.npmjs.com/cli/run-script) to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"release\": \"commit-and-tag-version\"\n  }\n}\n```\n\nNow you can use `npm run release` in place of `npm version`.\n\nThis 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.\n\n### As global `bin`\n\nInstall globally (add to your `PATH`):\n\n```\nnpm i -g commit-and-tag-version\n```\n\nNow you can use `commit-and-tag-version` in place of `npm version`.\n\nThis has the benefit of allowing you to use `commit-and-tag-version` on any repo/package without adding a dev dependency to each one.\n\n### Using `npx`\n\nAs 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`.\n\nThis method is especially useful when using `commit-and-tag-version` in non-JavaScript projects.\n\n## Configuration\n\nYou can configure `commit-and-tag-version` either by:\n\n1. Placing a `commit-and-tag-version` stanza in your `package.json` (assuming\n   your project is JavaScript).\n\n   \u003e Note for users who have migrated to\n   `commit-and-tag-version` from `standard-version`: the previous package.json configuration key of `standard-version` will still work.\n\n2. Creating a `.versionrc`, `.versionrc.json` or `.versionrc.js`.\n\n- If you are using a `.versionrc.js` your default export must be a configuration object, or a function returning a configuration object.\n\nAny of the command line parameters accepted by `commit-and-tag-version` can instead\nbe provided via configuration. Please refer to the [conventional-changelog-config-spec](https://github.com/conventional-changelog/conventional-changelog-config-spec/) for details on available configuration options.\n\n### Customizing CHANGELOG Generation\n\nBy default, `commit-and-tag-version` uses the [conventionalcommits preset](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits).\n\nThis preset adheres closely to the [conventionalcommits.org](https://www.conventionalcommits.org) specification.\n\nSuppose you're using GitLab, rather than GitHub, you might modify the following variables:\n\n- `commitUrlFormat`: the URL format of commit SHAs detected in commit messages.\n- `compareUrlFormat`: the URL format used to compare two tags.\n- `issueUrlFormat`: the URL format used to link to issues.\n\nMaking these URLs match GitLab's format, rather than GitHub's.\n\n### Deeper customization\n\nYou can override both [parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser) and [writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-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:\n\n```json\n{\n  \"commit-and-tag-version\": {\n    \"writerOpts\": {\n      \"commitsSort\": false\n    }\n  }\n}\n```\n\n## CLI Usage\n\n\u003e **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`.\n\n### First Release\n\nTo generate your changelog for your first release, simply do:\n\n```sh\n# npm run script\nnpm run release -- --first-release\n# global bin\ncommit-and-tag-version --first-release\n# npx\nnpx commit-and-tag-version --first-release\n```\n\nThis will tag a release **without bumping the version `bumpFiles`[1]()**.\n\nWhen you are ready, push the git tag and `npm publish` your first release. \\o/\n\n### Cutting Releases\n\nIf you typically use `npm version` to cut a new release, do this instead:\n\n```sh\n# npm run script\nnpm run release\n# or global bin\ncommit-and-tag-version\n```\n\nAs 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/\n\nAfter you cut a release, you can push the new git tag and `npm publish` (or `npm publish --tag next`) when you're ready.\n\n### Release as a Pre-Release\n\nUse the flag `--prerelease` to generate pre-releases:\n\nSuppose the last version of your code is `1.0.0`, and your code to be committed has patched changes. Run:\n\n```bash\n# npm run script\nnpm run release -- --prerelease\n```\n\nThis will tag your version as: `1.0.1-0`.\n\nIf you want to name the pre-release, you specify the name via `--prerelease \u003cname\u003e`.\n\nFor example, suppose your pre-release should contain the `alpha` prefix:\n\n```bash\n# npm run script\nnpm run release -- --prerelease alpha\n```\n\nThis will tag the version as: `1.0.1-alpha.0`\n\n#### Prerelease Tag Collision Avoidance\n\nWhen 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.\n\nFor example, if you're working with multiple prerelease channels simultaneously:\n\n```bash\ncommit-and-tag-version --prerelease xyz  # Creates v1.4.3-xyz.0\ncommit-and-tag-version --prerelease abc  # Creates v1.4.3-abc.0\ncommit-and-tag-version --prerelease xyz  # Creates v1.4.3-xyz.1 (auto-incremented)\n```\n\nThis 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.\n\n### Release as a Target Type Imperatively (`npm version`-like)\n\nTo forgo the automated version bump use `--release-as` with the argument `major`, `minor` or `patch`.\n\nSuppose the last version of your code is `1.0.0`, you've only landed `fix:` commits, but\nyou would like your next release to be a `minor`. Simply run the following:\n\n```bash\n# npm run script\nnpm run release -- --release-as minor\n# Or\nnpm run release -- --release-as 1.1.0\n```\n\nYou will get version `1.1.0` rather than what would be the auto-generated version `1.0.1`.\n\n\u003e **NOTE:** you can combine `--release-as` and `--prerelease` to generate a release. This is useful when publishing experimental feature(s).\n\n### Prevent Git Hooks\n\nIf 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:\n\n```sh\n# npm run script\nnpm run release -- --no-verify\n# or global bin\ncommit-and-tag-version --no-verify\n```\n\n### Custom Config Path\n\nSpecify a custom path to the configuration file using the `--config` option\n\n```sh\ncommit-and-tag-version --config ./path/to/.versionrc.js\n\n# or using alias\ncommit-and-tag-version -c ./path/to/.versionrc.js\n```\n\nAll config file formats can be used:\n\n```sh\ncommit-and-tag-version -c ./path/to/.versionrc[.js|.cjs|.json]\n```\n\n### Signing Commits and Tags\n\nIf you have your GPG key set up, add the `--sign` or `-s` flag to your `commit-and-tag-version` command.\n\n### Signed-off-by trailer\n\nTo add the \"Signed-off-by\" trailer to the commit message add the `--signoff` flag to your `commit-and-tag-version` command.\n\n### Lifecycle Scripts\n\n`commit-and-tag-version` supports lifecycle scripts. These allow you to execute your\nown supplementary commands during the release. The following\nhooks are available and execute in the order documented:\n\n- `prerelease`: executed before anything happens. If the `prerelease` script returns a\n  non-zero exit code, versioning will be aborted, but it has no other effect on the\n  process.\n- `prebump`/`postbump`: executed before and after the version is bumped. If the `prebump`\n  script returns a version #, it will be used rather than\n  the version calculated by `commit-and-tag-version`.\n- `prechangelog`/`postchangelog`: executes before and after the CHANGELOG is generated.\n- `precommit`/`postcommit`: called before and after the commit step.\n- `pretag`/`posttag`: called before and after the tagging step.\n\nSimply add the following to your package.json to configure lifecycle scripts:\n\n```json\n{\n  \"commit-and-tag-version\": {\n    \"scripts\": {\n      \"prebump\": \"echo 9.9.9\"\n    }\n  }\n}\n```\n\nAs an example to change from using GitHub to track your items to using your projects Jira use a\n`postchangelog` script to replace the url fragment containing '\u003chttps://github.com/`myproject`/issues/\u003e'\nwith a link to your Jira - assuming you have already installed [replace](https://www.npmjs.com/package/replace)\n\n```json\n{\n  \"commit-and-tag-version\": {\n    \"scripts\": {\n      \"postchangelog\": \"replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md\"\n    }\n  }\n}\n```\n\n### Skipping Lifecycle Steps\n\nYou can skip any of the lifecycle steps (`bump`, `changelog`, `commit`, `tag`),\nby adding the following to your package.json:\n\n```json\n{\n  \"commit-and-tag-version\": {\n    \"skip\": {\n      \"changelog\": true\n    }\n  }\n}\n```\n\n### Committing Generated Artifacts in the Release Commit\n\nIf you want to commit generated artifacts in the release commit, you can use the `--commit-all` or `-a` flag. You will need to stage the artifacts you want to commit, so your `release` command could look like this:\n\n```json\n{\n  \"commit-and-tag-version\": {\n    \"scripts\": {\n      \"prerelease\": \"webpack -p --bail \u0026\u0026 git add \u003cfile(s) to commit\u003e\"\n    }\n  }\n}\n```\n\n```json\n{\n  \"scripts\": {\n    \"release\": \"commit-and-tag-version -a\"\n  }\n}\n```\n\n### Dry Run Mode\n\nrunning `commit-and-tag-version` with the flag `--dry-run` allows you to see what\ncommands would be run, without committing to git or updating files.\n\n```sh\n# npm run script\nnpm run release -- --dry-run\n# or global bin\ncommit-and-tag-version --dry-run\n```\n\n### Prefix Tags\n\nTags are prefixed with `v` by default. If you would like to prefix your tags with something else, you can do so with the `-t` flag.\n\n```sh\ncommit-and-tag-version -t @scope/package\\@\n```\n\nThis will prefix your tags to look something like `@scope/package@2.0.0`\n\nIf you do not want to have any tag prefix you can use the `-t` flag and provide it with an **empty string** as value.\n\n\u003e Note: simply -t or --tag-prefix without any value will fallback to the default 'v'\n\n### Tag replacement\n\nIf you've already run `commit-and-tag-version` when creating your release, you may want to alter the release content and changelog without bumping\nthe version, by using `commit-and-tag-version --skip.bump`. By default, tagging with an already existing tag make `git` fails.\nYou can add the `--tag-force` flag to make use of `-f` option when calling `git tag`, then the existing version tag will be replaced.\n\n### Generate changelogs for old releases\n\nNormally 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#releasecount).\n\nWhen setting releaseCount=0 the whole changelog gets regenerated and replaced.\n\nYou can set the option either in the`.versionrc` file or inside `package.json` like below\n\n```json\n//.versionrc\n{\n  \"releaseCount\": 0\n}\n\n//package.json\n\n\"commit-and-tag-version\": {\n  \"releaseCount\": 0\n}\n```\n\n### CLI Help\n\n```sh\n# npm run script\nnpm run release -- --help\n# or global bin\ncommit-and-tag-version --help\n```\n\n## Code Usage\n\n```js\nconst commitAndTagVersion = require(\"commit-and-tag-version\");\n\n// Options are the same as command line, except camelCase\n// commitAndTagVersion returns a Promise\ncommitAndTagVersion({\n  noVerify: true,\n  infile: \"docs/CHANGELOG.md\",\n  silent: true,\n})\n  .then(() =\u003e {\n    // commit-and-tag-version is done\n  })\n  .catch((err) =\u003e {\n    console.error(`commit-and-tag-version failed with message: ${err.message}`);\n  });\n```\n\n_TIP: Use the `silent` option to prevent `commit-and-tag-version` from printing to the `console`._\n\n## FAQ\n\n### How is `commit-and-tag-version` different from `semantic-release`?\n\n[`semantic-release`](https://github.com/semantic-release/semantic-release) is described as:\n\n\u003e semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.\n\nWhile 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.\n\nWe 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.\n\n### Should I always squash commits when merging PRs?\n\nThe instructions to squash commits when merging pull requests assumes that **one PR equals, at most, one feature or fix**.\n\nIf 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.\n\nAlthough 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.\n\nFor 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.\n\n### Can I use `commit-and-tag-version` for additional metadata files, languages or version files?\n\nYou can configure multiple `bumpFiles` and `packageFiles`:\n\n1. Specify a custom `bumpFile` \"`filename`\", this is the path to the file you want to \"bump\"\n2. Specify the `bumpFile` \"`updater`\", this is _how_ the file will be bumped.\n   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`.\n   b. If your using an less-common version file, you can create your own `updater`.\n\n```js\n// .versionrc\n{\n  \"bumpFiles\": [\n    {\n      \"filename\": \"MY_VERSION_TRACKER.txt\",\n      // The `plain-text` updater assumes the file contents represents the version.\n      \"type\": \"plain-text\"\n    },\n    {\n      \"filename\": \"a/deep/package/dot/json/file/package.json\",\n      // The `json` updater assumes the version is available under a `version` key in the provided JSON document.\n      \"type\": \"json\"\n    },\n    {\n      \"filename\": \"VERSION_TRACKER.json\",\n      //  See \"Custom `updater`s\" for more details.\n      \"updater\": \"commit-and-tag-version-updater.js\"\n    }\n  ]\n}\n```\n\nIf using `.versionrc.js` as your configuration file, the `updater` may also be set as an object, rather than a path:\n\n```js\n// .versionrc.js\nconst tracker = {\n  filename: \"VERSION_TRACKER.json\",\n  updater: require(\"./path/to/custom-version-updater\"),\n};\n\nmodule.exports = {\n  bumpFiles: [tracker],\n  packageFiles: [tracker],\n};\n```\n\n#### Custom `updater`s\n\nAn `updater` is expected to be a Javascript module with _atleast_ two methods exposed: `readVersion` and `writeVersion`.\n\n##### `readVersion(contents = string): string`\n\nThis method is used to read the version from the provided file contents.\n\nThe return value is expected to be a semantic version string.\n\n##### `writeVersion(contents = string, version: string): string`\n\nThis method is used to write the version to the provided contents.\n\nThe return value will be written directly (overwrite) to the provided file.\n\n---\n\nLet's assume our `VERSION_TRACKER.json` has the following contents:\n\n```json\n{\n  \"tracker\": {\n    \"package\": {\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\nAn acceptable `commit-and-tag-version-updater.js` would be:\n\n```js\n// commit-and-tag-version-updater.js\nconst stringifyPackage = require(\"stringify-package\");\nconst detectIndent = require(\"detect-indent\");\nconst detectNewline = require(\"detect-newline\");\n\nmodule.exports.readVersion = function (contents) {\n  return JSON.parse(contents).tracker.package.version;\n};\n\nmodule.exports.writeVersion = function (contents, version) {\n  const json = JSON.parse(contents);\n  let indent = detectIndent(contents).indent;\n  let newline = detectNewline(contents);\n  json.tracker.package.version = version;\n  return stringifyPackage(json, indent, newline);\n};\n```\n\n### Why do breaking changes before 1.0.0 not trigger a 1.0.0 release?\n\nBelow 1.0.0, the semver specification doesn't give any guarantees about the\nmeaning of version numbers. However, with npm there is a community convention,\nand implementation-defined behaviour: If your version is between 0.1.0 and\n1.0.0, npm treats an update to the minor version as a breaking change - that is\n^0.1.0 will match 0.1.2 but not 0.2.0. Rust's cargo package manager also behaves\nthe same way.\n\nThis tool (via conventional-commits) also follows that convention - breaking\nchanges below v1.0.0 are treated as a minor version bump. Here's an example\nseries of commits with tagged versions:\n\n```\n1017b00 chore: initial commit\n9e2ba95 (tag: v0.0.2) chore(release): 0.0.2\n3598012 fix!: Example breaking change\n1a4994a (tag: v0.1.0) chore(release): 0.1.0\n```\n\nSemver's only guarantee is \"all bets are off\", but npm has made a choice about\nwhat bets to make. `commit-and-tag-version` follows the same convention (along\nwith other package managers for other ecosystems).\n\nWhen you are ready to release v1.0.0, add `--release-as 1.0.0` to the options.\n\n### Why do my `refactor`, `chore` etc changes not appear in the changelog?\n\nBy 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.\n\nConventional commits is meant to make it easy for machines to reason about the user-facing changes,\nand the changelog generation makes it easy for humans to consume this information too. \nUsually, you wouldn't want non-user facing changes like refactor in the changelog. \n\n## License\n\nISC\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsolute-version%2Fcommit-and-tag-version","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabsolute-version%2Fcommit-and-tag-version","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsolute-version%2Fcommit-and-tag-version/lists"}