Skip to content

docs(bump): add missing --allow-no-commit behaviors and other minor d… #1656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(bump): add missing --allow-no-commit behaviors and other minor d… #1656

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 46 additions & 32 deletions docs/commands/bump.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).
Expand Down Expand Up @@ -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.

Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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`

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down