Skip to content

Commit 2fa81c7

Browse files
bearomorphismLee-W
bearomorphism
and
Lee-W
committed
docs(config): split the configuration documentation into pages
Co-authored-by: Wei Lee <weilee.rx@gmail.com>
1 parent b565e4b commit 2fa81c7

20 files changed

+1489
-1243
lines changed

‎docs/commands/bump.md‎

Lines changed: 20 additions & 213 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ It analyzes your commits to determine the appropriate version increment accordin
1111

1212
We will use `pyproject.toml` as the configuration file throughout the documentation.
1313

14-
See [Configuration file](../config.md#configuration-file) for more details.
14+
See [Configuration file](../config/configuration_file.md) for more details.
1515

1616
## Key Features
1717

@@ -30,7 +30,7 @@ The version follows the `MAJOR.MINOR.PATCH` format, with increments determined b
3030
| `MINOR` | New features | `feat` |
3131
| `PATCH` | Fixes and improvements | `fix`, `perf`, `refactor`|
3232

33-
### Version Schemes (`--version-scheme`)
33+
### `--version-scheme`
3434

3535
By default, Commitizen uses [PEP 440][pep440] for version formatting. You can switch to semantic versioning using either:
3636

@@ -50,7 +50,7 @@ Available options are:
5050
- `pep440`: [PEP 440][pep440] (**default** and recommended for Python projects)
5151
- `semver`: [Semantic Versioning][semver] (recommended for non-Python projects)
5252

53-
You can also set this in the [configuration](#version_scheme) with `version_scheme = "semver"`.
53+
You can also set this in the configuration file with `version_scheme = "semver"`.
5454

5555
!!! note
5656
[pep440][pep440] and [semver][semver] are quite similar, although their difference lies in
@@ -111,7 +111,7 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several
111111

112112
### `--files-only`
113113

114-
Bumps the version in the files defined in [`version_files`](#version_files) without creating a commit and tag on the git repository.
114+
Bumps the version in the files defined in [`version_files`][version_files] without creating a commit and tag on the git repository.
115115

116116
```bash
117117
cz bump --files-only
@@ -178,7 +178,7 @@ The following table illustrates the difference in behavior between the two modes
178178

179179
### `--check-consistency`
180180

181-
Check whether the versions defined in [`version_files`](#version_files) and the version in Commitizen configuration are consistent before bumping version.
181+
Check whether the versions defined in [version_files][version_files] and the version in Commitizen configuration are consistent before bumping version.
182182

183183
```bash
184184
cz bump --check-consistency
@@ -207,7 +207,7 @@ from setuptools import setup
207207
setup(..., version="1.0.5", ...)
208208
```
209209

210-
When you run `cz bump --check-consistency`, Commitizen will verify that the current version in `pyproject.toml` (`1.21.0`) exists in all files listed in [`version_files`](#version_files).
210+
When you run `cz bump --check-consistency`, Commitizen will verify that the current version in `pyproject.toml` (`1.21.0`) exists in all files listed in [version_files][version_files].
211211
In this example, it will detect that `setup.py` contains `1.0.5` instead of `1.21.0`, causing the bump to fail.
212212

213213
!!! warning "Partial updates on failure"
@@ -260,6 +260,9 @@ For example, in `pyproject.toml`:
260260
annotated_tag = true
261261
```
262262

263+
!!! note
264+
By default, Commitizen uses lightweight tags.
265+
263266
### `--annotated-tag-message`
264267

265268
Create annotated tags with the given message.
@@ -351,10 +354,13 @@ Creates gpg signed tags.
351354
cz bump --gpg-sign
352355
```
353356

357+
!!! note
358+
By default, Commitizen uses lightweight tags.
359+
354360
### `--template`
355361

356362
Provides your own changelog jinja template.
357-
See [the template customization section](../customization.md#customizing-the-changelog-template)
363+
See [the template customization section](../customization/changelog_template.md)
358364

359365
### `--extra`
360366

@@ -364,7 +370,7 @@ Provides your own changelog extra variables by using the `extras` settings or th
364370
cz bump --changelog --extra key=value -e short="quoted value"
365371
```
366372

367-
See [the template customization section](../customization.md#customizing-the-changelog-template).
373+
See [the template customization section](../customization/changelog_template.md).
368374

369375
### `--build-metadata`
370376

@@ -451,15 +457,13 @@ Allow the project version to be bumped even when there's no eligible version.
451457
cz bump --allow-no-commit
452458
```
453459

454-
### `--version-scheme`
455-
456-
See [Version Schemes](#version-schemes-version-scheme).
457-
458-
## Configuration file options
460+
# bump version to 2.0.0 even when there's no breaking changes or even no commits
461+
cz bump --allow-no-commit 2.0.0
462+
```
459463

460-
### `tag_format`
464+
### `--tag-format`
461465

462-
`tag_format` and [`version_scheme`](#version-schemes-version-scheme) are combined to make Git tag names from versions.
466+
`tag_format` and [version_scheme][version_scheme] are combined to make Git tag names from versions.
463467

464468
These are used in:
465469

@@ -501,200 +505,6 @@ Supported variables:
501505
| `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) |
502506
| `$devrelease`, `${devrelease}` | Development release |
503507

504-
### `version_files`
505-
506-
Identify the files or glob patterns which should be updated with the new version.
507-
508-
Commitizen will update its configuration file automatically when bumping,
509-
regardless of whether the file is present or not in `version_files`.
510-
511-
You may specify the `version_files` in your configuration file.
512-
513-
```toml title="pyproject.toml"
514-
[tool.commitizen]
515-
version_files = [
516-
"src/__version__.py",
517-
]
518-
```
519-
520-
It is also possible to provide a pattern for each file, separated by a colon (e.g. `file:pattern`). See the below example for more details.
521-
522-
```toml title="pyproject.toml"
523-
[tool.commitizen]
524-
version_files = [
525-
"packages/*/pyproject.toml:version",
526-
"setup.json:version",
527-
]
528-
```
529-
530-
#### Example scenario
531-
532-
We have a project with the following configuration file `pyproject.toml`:
533-
534-
```toml title="pyproject.toml"
535-
[tool.commitizen]
536-
version_files = [
537-
"src/__version__.py",
538-
"packages/*/pyproject.toml:version",
539-
"setup.json:version",
540-
]
541-
```
542-
543-
For the reference `"setup.json:version"`, it means that it will look for a file `setup.json` and will only change the lines that contain the substring `"version"`.
544-
545-
For example, if the content of `setup.json` is:
546-
547-
<!-- DEPENDENCY: repeated_version_number.json -->
548-
549-
```json title="setup.json"
550-
{
551-
"name": "magictool",
552-
"version": "1.2.3",
553-
"dependencies": {
554-
"lodash": "1.2.3"
555-
}
556-
}
557-
```
558-
559-
After running `cz bump 2.0.0`, its content will be updated to:
560-
561-
```diff title="setup.json"
562-
{
563-
"name": "magictool",
564-
- "version": "1.2.3",
565-
+ "version": "2.0.0",
566-
"dependencies": {
567-
"lodash": "1.2.3"
568-
}
569-
}
570-
```
571-
572-
!!! note
573-
Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
574-
575-
!!! note "Historical note"
576-
This option was renamed from `files` to `version_files`.
577-
578-
### `bump_message`
579-
580-
Template used to specify the commit message generated when bumping.
581-
582-
Defaults to: `bump: version $current_version → $new_version`
583-
584-
| Variable | Description |
585-
| ------------------ | ----------------------------------- |
586-
| `$current_version` | the version existing before bumping |
587-
| `$new_version` | version generated after bumping |
588-
589-
#### Example configuration
590-
591-
```toml title="pyproject.toml"
592-
[tool.commitizen]
593-
bump_message = "release $current_version → $new_version [skip-ci]"
594-
```
595-
596-
### `update_changelog_on_bump`
597-
598-
When set to `true`, `cz bump` is equivalent to `cz bump --changelog`.
599-
600-
```toml title="pyproject.toml"
601-
[tool.commitizen]
602-
update_changelog_on_bump = true
603-
```
604-
605-
### `annotated_tag`
606-
607-
When set to `true`, `cz bump` is equivalent to `cz bump --annotated-tag`.
608-
609-
```toml title="pyproject.toml"
610-
[tool.commitizen]
611-
annotated_tag = true
612-
```
613-
614-
### `gpg_sign`
615-
616-
When set to `true`, `cz bump` is equivalent to `cz bump --gpg-sign`. See [--gpg-sign](#-gpg-sign).
617-
618-
```toml title="pyproject.toml"
619-
[tool.commitizen]
620-
gpg_sign = true
621-
```
622-
623-
### `major_version_zero`
624-
625-
When set to `true`, `cz bump` is equivalent to `cz bump --major-version-zero`. See [--major-version-zero](#-major-version-zero).
626-
627-
```toml title="pyproject.toml"
628-
[tool.commitizen]
629-
major_version_zero = true
630-
```
631-
632-
### `pre_bump_hooks`
633-
634-
A list of optional commands that will run right _after_ updating [`version_files`](#version_files)
635-
and _before_ actual committing and tagging the release.
636-
637-
Useful when you need to generate documentation based on the new version. During
638-
execution of the script, some environment variables are available:
639-
640-
| Variable | Description |
641-
| ---------------------------- | ---------------------------------------------------------- |
642-
| `CZ_PRE_IS_INITIAL` | `True` when this is the initial release, `False` otherwise |
643-
| `CZ_PRE_CURRENT_VERSION` | Current version, before the bump |
644-
| `CZ_PRE_CURRENT_TAG_VERSION` | Current version tag, before the bump |
645-
| `CZ_PRE_NEW_VERSION` | New version, after the bump |
646-
| `CZ_PRE_NEW_TAG_VERSION` | New version tag, after the bump |
647-
| `CZ_PRE_MESSAGE` | Commit message of the bump |
648-
| `CZ_PRE_INCREMENT` | Whether this is a `MAJOR`, `MINOR` or `PATCH` release |
649-
| `CZ_PRE_CHANGELOG_FILE_NAME` | Path to the changelog file, if available |
650-
651-
```toml title="pyproject.toml"
652-
[tool.commitizen]
653-
pre_bump_hooks = [
654-
"scripts/generate_documentation.sh"
655-
]
656-
```
657-
658-
### `post_bump_hooks`
659-
660-
A list of optional commands that will run right _after_ committing and tagging the release.
661-
662-
Useful when you need to send notifications about a release, or further automate deploying the
663-
release. During execution of the script, some environment variables are available:
664-
665-
| Variable | Description |
666-
| ------------------------------ | ----------------------------------------------------------- |
667-
| `CZ_POST_WAS_INITIAL` | `True` when this was the initial release, `False` otherwise |
668-
| `CZ_POST_PREVIOUS_VERSION` | Previous version, before the bump |
669-
| `CZ_POST_PREVIOUS_TAG_VERSION` | Previous version tag, before the bump |
670-
| `CZ_POST_CURRENT_VERSION` | Current version, after the bump |
671-
| `CZ_POST_CURRENT_TAG_VERSION` | Current version tag, after the bump |
672-
| `CZ_POST_MESSAGE` | Commit message of the bump |
673-
| `CZ_POST_INCREMENT` | Whether this was a `MAJOR`, `MINOR` or `PATCH` release |
674-
| `CZ_POST_CHANGELOG_FILE_NAME` | Path to the changelog file, if available |
675-
676-
```toml title="pyproject.toml"
677-
[tool.commitizen]
678-
post_bump_hooks = [
679-
"scripts/slack_notification.sh"
680-
]
681-
```
682-
683-
### `prerelease_offset`
684-
685-
Offset with which to start counting prereleases.
686-
687-
Defaults to: `0`
688-
689-
```toml title="pyproject.toml"
690-
[tool.commitizen]
691-
prerelease_offset = 1
692-
```
693-
694-
### `version_scheme`
695-
696-
See [Version Schemes](#version-schemes-version-scheme).
697-
698508
## Avoid raising errors
699509

700510
Some situations from Commitizen raise an exit code different from 0.
@@ -758,9 +568,6 @@ on the list, and then you can use the exit code:
758568
cz -nr 21 bump
759569
```
760570

761-
## Custom bump
762-
763-
Read the [customizing section](../customization.md).
764-
765571
[pep440]: https://www.python.org/dev/peps/pep-0440/
766572
[semver]: https://semver.org/
573+
[version_files]: ../config/bump.md#version_files

0 commit comments

Comments
 (0)