From ff3a457b9430966a016c5c0064cd397f2bf0ec76 Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Wed, 19 Nov 2025 14:57:47 +0800 Subject: [PATCH] docs(bump): add missing --allow-no-commit behaviors and other minor documentation changes --- docs/commands/bump.md | 78 +++++++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 32 deletions(-) diff --git a/docs/commands/bump.md b/docs/commands/bump.md index eb807f841..8444e35c4 100644 --- a/docs/commands/bump.md +++ b/docs/commands/bump.md @@ -111,7 +111,7 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several ### `--files-only` -Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository, +Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository. ```bash cz bump --files-only @@ -128,7 +128,7 @@ cz bump --changelog ### `--prerelease` The bump is a pre-release bump, meaning that in addition to a possible version bump the new version receives a -pre-release segment compatible with the bump’s version scheme, where the segment consist of a _phase_ and a +pre-release segment compatible with the bump's version scheme, where the segment consists of a _phase_ and a non-negative number. Supported options for `--prerelease` are the following phase names `alpha`, `beta`, or `rc` (release candidate). For more details, refer to the [Python Packaging User Guide](https://packaging.python.org/en/latest/specifications/version-specifiers/#pre-releases). @@ -280,19 +280,20 @@ Any other messages generated by `cz bump` will be sent to `stderr`. When this flag is used, `--changelog` is implied. However, it is recommended to set `--changelog` (or the setting `update_changelog_on_bump`) explicitly when the option `--changelog-to-stdout` is used. -#### Useful scenarios +!!! note "Useful scenarios" + Pipe the newly created changelog to another tool. -This is useful to pipe the newly created changelog to another tool. For example, it can be sent to an auditing system, or to create a GitHub Release, etc. + The output can be redirected to an auditing system, or used to create a GitHub Release, etc. -```bash -cz bump --changelog --changelog-to-stdout > body.md -``` + ```bash + cz bump --changelog --changelog-to-stdout > body.md + ``` ### `--git-output-to-stderr` -If `--git-output-to-stderr` is used, git commands output is redirected to `stderr`. +Redirects git commands output to `stderr`. -Useful when used with `--changelog-to-stdout` and piping the output to a file, +Useful when used with `--changelog-to-stdout` and piping the output to a file. For example, `git commit` output may pollute `stdout`, so it is recommended to use this flag when piping the output to a file. @@ -305,7 +306,7 @@ Useful to combine with code formatters, like [Prettier](https://prettier.io/). ### `--major-version-zero` -Breaking changes does not bump the major version number. +Breaking changes do not bump the major version number. Say you have a project with the version `0.1.x` and you commit a breaking change like this: @@ -343,7 +344,7 @@ Then the version of your project will be bumped to `0.2.0` instead of `1.0.0`. ### `--gpg-sign` -Create gpg signed tags. +Creates gpg signed tags. ```bash cz bump --gpg-sign @@ -366,18 +367,16 @@ See [the template customization section](../customization.md#customizing-the-cha ### `--build-metadata` -Provides a way to specify additional metadata in the version string. This parameter is not compatible with `--local-version` as it uses the same part of the version string. +Specifies additional metadata in the version string. ```bash +# creates a version like `1.1.2+yourmetadata`. cz bump --build-metadata yourmetadata ``` -Will create a version like `1.1.2+yourmetadata`. - -This can be useful for multiple things - -- Git hash in version -- Labeling the version with additional metadata. +!!! note "Example usage" + - Git hash in version + - Labeling the version with additional metadata. !!! note Commitizen ignores everything after `+` when it bumps the version. @@ -391,16 +390,19 @@ This can be useful for multiple things - Version `1.2.3+a`, and `1.2.3+b` are the same version! Tools should not use the string after `+` for version calculation. This is probably not a guarantee (example in helm) even tho it is in the spec. - It might be problematic having the metadata in place when doing upgrades depending on what tool you use. +!!! warning + This parameter is not compatible with `--local-version` as it uses the same part of the version string. + ### `--get-next` -Provides a way to determine the next version and write it to stdout. This parameter is not compatible with `--changelog` -and `manual version`. +Similar to `--dry-run` but only outputs the next version. ```bash +# outputs 1.0.1 if the current version is 1.0.0 and the increment is PATCH cz bump --get-next ``` -Will only output the next version, e.g., `1.2.3`. This can be useful for determining the next version based on CI for non-production environments/builds. +Useful for determining the next version based on CI for non-production environments/builds. !!! note "Compare with `--dry-run`" `--dry-run` provides a more detailed output including the changes as they would appear in the changelog file, while `--get-next` only outputs the next version. @@ -426,15 +428,27 @@ Will only output the next version, e.g., `1.2.3`. This can be useful for determi ### `--allow-no-commit` -Allow the project version to be bumped even when there's no eligible version. This is most useful when used with `--increment {MAJOR,MINOR,PATCH}` or `[MANUAL_VERSION]` +Allow the project version to be bumped even when there's no eligible version. -```sh -# bump a minor version even when there's only bug fixes, documentation changes or even no commits -cz bump --incremental MINOR --allow-no-commit +!!! note "Example usage" + ```sh + # bump a minor version even when there's only bug fixes, documentation changes or even no commits -# bump version to 2.0.0 even when there's no breaking changes changes or even no commits -cz bump --allow-no-commit 2.0.0 -``` + cz bump --increment MINOR --allow-no-commit + + # bump version to 2.0.0 even when there's no breaking changes or even no commits + cz bump --allow-no-commit 2.0.0 + ``` + +!!! note "Default increment" + The increment is overridden to `PATCH` if there is no increment detected or specified. + + In other words, `cz bump --allow-no-commit` allows you to bump the version to the next patch version even when there is no eligible commit. + + ```sh + # will bump to `1.0.1` if the current version is `1.0.0`. + cz bump --allow-no-commit + ``` ### `--version-scheme` @@ -479,19 +493,19 @@ Supported variables: | Variable | Description | |--------------------------------|---------------------------------------------| -| `$version`, `${version}` | fully generated version | +| `$version`, `${version}` | fully generated version | | `$major`, `${major}` | MAJOR increment | | `$minor`, `${minor}` | MINOR increment | | `$patch`, `${patch}` | PATCH increment | | `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) | -| `$devrelease`, ${devrelease}` | Development release | +| `$devrelease`, `${devrelease}` | Development release | ### `version_files` Identify the files or glob patterns which should be updated with the new version. Commitizen will update its configuration file automatically when bumping, -regarding if the file is present or not in `version_files`. +regardless of whether the file is present or not in `version_files`. You may specify the `version_files` in your configuration file. @@ -685,7 +699,7 @@ See [Version Schemes](#version-schemes-version-scheme). Some situations from Commitizen raise an exit code different from 0. If the error code is different from 0, any CI or script running Commitizen might be interrupted. -If you have a special use case, where you don't want to raise one of this error codes, you can +If you have a special use case, where you don't want to raise one of these error codes, you can tell Commitizen to not raise them. ### Recommended use case