Skip to content

Commit 2292b1e

Browse files
woilewoile
committed
docs(config): make settings shareable
1 parent f26e3c1 commit 2292b1e

File tree

2 files changed

+183
-28
lines changed

2 files changed

+183
-28
lines changed

‎docs/config.md

Lines changed: 181 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,32 +2,185 @@
22

33
## Settings
44

5-
| Variable | Type | Default | Description |
6-
| ---------------------------- | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7-
| `name` | `str` | `"cz_conventional_commits"` | Name of the committing rules to use |
8-
| `version` | `str` | `None` | Current version. Example: "0.1.2" |
9-
| `version_files` | `list` | `[ ]` | Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files] |
10-
| `version_provider` | `str` | `commitizen` | Version provider used to read and write version [Read more](#version-providers) |
11-
| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [Read more][tag_format] |
12-
| `update_changelog_on_bump` | `bool` | `false` | Create changelog when running `cz bump` |
13-
| `gpg_sign` | `bool` | `false` | Use gpg signed tags instead of lightweight tags. |
14-
| `annotated_tag` | `bool` | `false` | Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight] |
15-
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [Read more][bump_message] |
16-
| `allow_abort` | `bool` | `false` | Disallow empty commit messages, useful in ci. [Read more][allow_abort] |
17-
| `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog |
18-
| `changelog_incremental` | `bool` | `false` | Update changelog with the missing versions. This is good if you don't want to replace previous versions in the file. Note: when doing `cz bump --changelog` this is automatically set to `true` |
19-
| `changelog_start_rev` | `str` | `None` | Start from a given git rev to generate the changelog |
20-
| `changelog_merge_prerelease` | `bool` | `false` | Collect all changes of prerelease versions into the next non-prerelease version when creating the changelog. |
21-
| `style` | `list` | see above | Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)][additional-features] |
22-
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [Read more][customization] |
23-
| `use_shortcuts` | `bool` | `false` | If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [Read more][shortcuts] |
24-
| `major_version_zero` | `bool` | `false` | When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [major-version-zero] |
25-
| `prerelease_offset` | `int` | `0` | In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset] |
26-
| `version_type` | `str` | `pep440` | Select a version type from the following options [`pep440`, `semver`]. Useful for non-python projects. [Read more][version_type] |
27-
| `pre_bump_hooks` | `list[str]` | `[]` | Calls the hook scripts **before** bumping version. [Read more][pre_bump_hooks] |
28-
| `post_bump_hooks` | `list[str]` | `[]` | Calls the hook scripts **after** bumping the version. [Read more][post_bump_hooks] |
29-
30-
## pyproject.toml or .cz.toml
5+
### `name`
6+
7+
Type: `str`
8+
9+
Default: `"cz_conventional_commits"`
10+
11+
Name of the committing rules to use
12+
13+
### `version`
14+
15+
Type: `str`
16+
17+
Default: `None`
18+
19+
Current version. Example: "0.1.2". Required if you use `provider = "commitizen"`.
20+
21+
### `version_files`
22+
23+
Type: `list`
24+
25+
Default: `[ ]`
26+
27+
Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files]
28+
29+
### `version_provider`
30+
31+
Type: `str`
32+
33+
Default: `commitizen`
34+
35+
Version provider used to read and write version [Read more](#version-providers)
36+
37+
### `tag_format`
38+
39+
Type: `str`
40+
41+
Default: `None`
42+
43+
Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [Read more][tag_format]
44+
45+
### `update_changelog_on_bump`
46+
47+
Type: `bool`
48+
49+
Default: `false`
50+
51+
Create changelog when running `cz bump`
52+
53+
### `gpg_sign`
54+
55+
Type: `bool`
56+
57+
Default: `false`
58+
59+
Use gpg signed tags instead of lightweight tags.
60+
61+
### `annotated_tag`
62+
63+
Type: `bool`
64+
65+
Default: `false`
66+
67+
Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight]
68+
69+
### `bump_message`
70+
71+
Type: `str`
72+
73+
Default: `None`
74+
75+
Create custom commit message, useful to skip ci. [Read more][bump_message]
76+
77+
### `allow_abort`
78+
79+
Type: `bool`
80+
81+
Default: `false`
82+
83+
Disallow empty commit messages, useful in ci. [Read more][allow_abort]
84+
85+
### `changelog_file`
86+
87+
Type: `str`
88+
89+
Default: `CHANGELOG.md`
90+
91+
filename of exported changelog
92+
93+
### `changelog_incremental`
94+
95+
Type: `bool`
96+
97+
Default: `false`
98+
99+
Update changelog with the missing versions. This is good if you don't want to replace previous versions in the file. Note: when doing `cz bump --changelog` this is automatically set to `true`
100+
101+
### `changelog_start_rev`
102+
103+
Type: `str`
104+
105+
Default: `None`
106+
107+
Start from a given git rev to generate the changelog
108+
109+
### `changelog_merge_prerelease`
110+
111+
Type: `bool`
112+
113+
Default: `false`
114+
115+
Collect all changes of prerelease versions into the next non-prerelease version when creating the changelog.
116+
117+
### `style`
118+
119+
Type: `list`
120+
121+
see above
122+
123+
Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)][additional-features]
124+
125+
### `customize`
126+
127+
Type: `dict`
128+
129+
Default: `None`
130+
131+
**This is only supported when config through `toml`.** Custom rules for committing and bumping. [Read more][customization]
132+
133+
### `use_shortcuts`
134+
135+
Type: `bool`
136+
137+
Default: `false`
138+
139+
If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [Read more][shortcuts]
140+
141+
### `major_version_zero`
142+
143+
Type: `bool`
144+
145+
Default: `false`
146+
147+
When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [major-version-zero]
148+
149+
### `prerelease_offset`
150+
151+
Type: `int`
152+
153+
Default: `0`
154+
155+
In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset] |
156+
157+
### `version_type`
158+
159+
Type: `str`
160+
161+
Default: `pep440`
162+
163+
Select a version type from the following options [`pep440`, `semver`]. Useful for non-python projects. [Read more][version_type]
164+
165+
### `pre_bump_hooks`
166+
167+
Type: `list[str]`
168+
169+
Default: `[]`
170+
171+
Calls the hook scripts **before** bumping version. [Read more][pre_bump_hooks]
172+
173+
### `post_bump_hooks`
174+
175+
Type: `list[str]`
176+
177+
Default: `[]`
178+
179+
Calls the hook scripts **after** bumping the version. [Read more][post_bump_hooks]
180+
181+
## Configuration file
182+
183+
### pyproject.toml or .cz.toml
31184

32185
Default and recommended configuration format for a project.
33186
For a **python** project, we recommend adding an entry to your `pyproject.toml`.
@@ -58,7 +211,7 @@ style = [
58211
]
59212
```
60213

61-
## .cz.json or cz.json
214+
### .cz.json or cz.json
62215

63216
Commitizen has support for JSON configuration. Recommended for `NodeJS` projects.
64217

@@ -84,7 +237,7 @@ Commitizen has support for JSON configuration. Recommended for `NodeJS` projects
84237
}
85238
```
86239

87-
## .cz.yaml or cz.yaml
240+
### .cz.yaml or cz.yaml
88241

89242
YAML configuration is supported by Commitizen. Recommended for `Go`, `ansible`, or even `helm` charts projects.
90243

‎mkdocs.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,5 @@ markdown_extensions:
3939
- extra
4040
- pymdownx.highlight
4141
- pymdownx.superfences
42+
- toc:
43+
permalink: true

0 commit comments

Comments
 (0)