Skip to content

Commit 33d401f

Browse files
woilewoile
authored
Merge pull request #624 from commitizen-tools/docs/major-version
docs(config.md): list settings first and add missing param
2 parents dc10df0 + 4a93583 commit 33d401f

File tree

1 file changed

+69
-97
lines changed

1 file changed

+69
-97
lines changed

‎docs/config.md

Lines changed: 69 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,33 @@
11
# Configuration
22

3+
## Settings
4+
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 `:` [See more][version_files] |
10+
| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more][tag_format] |
11+
| `update_changelog_on_bump` | `bool` | `false` | Create changelog when running `cz bump` |
12+
| `gpg_sign` | `bool` | `false` | Use gpg signed tags instead of lightweight tags. |
13+
| `annotated_tag` | `bool` | `false` | Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight] |
14+
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more][bump_message] |
15+
| `allow_abort` | `bool` | `false` | Disallow empty commit messages, useful in ci. [See more][allow_abort] |
16+
| `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog |
17+
| `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` |
18+
| `changelog_start_rev` | `str` | `None` | Start from a given git rev to generate the changelog |
19+
| `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] |
20+
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more][customization] |
21+
| `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. [See more][shortcuts] |
22+
| `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] |
23+
324
## pyproject.toml or .cz.toml
425

5-
Add an entry to `pyproject.toml` or `.cz.toml`. Recommended for **python** projects.
26+
Default and recommended configuration format for a project.
27+
For a **python** project, we recommend adding an entry to your `pyproject.toml`.
28+
You can also create a `.cz.toml` file at the root of your project folder.
29+
30+
Example configuration:
631

732
```toml
833
[tool.commitizen]
@@ -26,123 +51,70 @@ style = [
2651
]
2752
```
2853

29-
`.cz.toml` is recommended for **other languages** projects (js, go, etc).
30-
3154
## .cz.json or cz.json
3255

33-
JSON might be a more common configuration format for non-python projects, so Commitizen supports JSON config files, now.
56+
Commitizen has support for JSON configuration. Recommended for `NodeJS` projects.
3457

3558
```json
3659
{
37-
"commitizen": {
38-
"name": "cz_conventional_commits",
39-
"version": "0.1.0",
40-
"version_files": [
41-
"src/__version__.py",
42-
"pyproject.toml:version"
43-
],
44-
"style": [
45-
[
46-
"qmark",
47-
"fg:#ff9d00 bold"
48-
],
49-
[
50-
"question",
51-
"bold"
52-
],
53-
[
54-
"answer",
55-
"fg:#ff9d00 bold"
56-
],
57-
[
58-
"pointer",
59-
"fg:#ff9d00 bold"
60-
],
61-
[
62-
"highlighted",
63-
"fg:#ff9d00 bold"
64-
],
65-
[
66-
"selected",
67-
"fg:#cc5454"
68-
],
69-
[
70-
"separator",
71-
"fg:#cc5454"
72-
],
73-
[
74-
"instruction",
75-
""
76-
],
77-
[
78-
"text",
79-
""
80-
],
81-
[
82-
"disabled",
83-
"fg:#858585 italic"
84-
]
85-
]
86-
}
60+
"commitizen": {
61+
"name": "cz_conventional_commits",
62+
"version": "0.1.0",
63+
"version_files": ["src/__version__.py", "pyproject.toml:version"],
64+
"style": [
65+
["qmark", "fg:#ff9d00 bold"],
66+
["question", "bold"],
67+
["answer", "fg:#ff9d00 bold"],
68+
["pointer", "fg:#ff9d00 bold"],
69+
["highlighted", "fg:#ff9d00 bold"],
70+
["selected", "fg:#cc5454"],
71+
["separator", "fg:#cc5454"],
72+
["instruction", ""],
73+
["text", ""],
74+
["disabled", "fg:#858585 italic"]
75+
]
76+
}
8777
}
8878
```
8979

9080
## .cz.yaml or cz.yaml
91-
YAML is another format for **non-python** projects as well, supported by Commitizen:
81+
82+
YAML configuration is supported by Commitizen. Recommended for `Go`, `ansible`, or even `helm` charts projects.
9283

9384
```yaml
9485
commitizen:
9586
name: cz_conventional_commits
9687
version: 0.1.0
9788
version_files:
98-
- src/__version__.py
99-
- pyproject.toml:version
89+
- src/__version__.py
90+
- pyproject.toml:version
10091
style:
101-
- - qmark
102-
- fg:#ff9d00 bold
103-
- - question
104-
- bold
105-
- - answer
106-
- fg:#ff9d00 bold
107-
- - pointer
108-
- fg:#ff9d00 bold
109-
- - highlighted
110-
- fg:#ff9d00 bold
111-
- - selected
112-
- fg:#cc5454
113-
- - separator
114-
- fg:#cc5454
115-
- - instruction
116-
- ''
117-
- - text
118-
- ''
119-
- - disabled
120-
- fg:#858585 italic
92+
- - qmark
93+
- fg:#ff9d00 bold
94+
- - question
95+
- bold
96+
- - answer
97+
- fg:#ff9d00 bold
98+
- - pointer
99+
- fg:#ff9d00 bold
100+
- - highlighted
101+
- fg:#ff9d00 bold
102+
- - selected
103+
- fg:#cc5454
104+
- - separator
105+
- fg:#cc5454
106+
- - instruction
107+
- ""
108+
- - text
109+
- ""
110+
- - disabled
111+
- fg:#858585 italic
121112
```
122113
123-
## Settings
124-
125-
| Variable | Type | Default | Description |
126-
|----------------------------| ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
127-
| `name` | `str` | `"cz_conventional_commits"` | Name of the committing rules to use |
128-
| `version` | `str` | `None` | Current version. Example: "0.1.2" |
129-
| `version_files` | `list` | `[ ]` | Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [See more][version_files] |
130-
| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more][tag_format] |
131-
| `update_changelog_on_bump` | `bool` | `false` | Create changelog when running `cz bump` |
132-
| `gpg_sign` | `bool` | `false` | Use gpg signed tags instead of lightweight tags. |
133-
| `annotated_tag` | `bool` | `false` | Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight] |
134-
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more][bump_message] |
135-
| `allow_abort` | `bool` | `false` | Disallow empty commit messages, useful in ci. [See more][allow_abort] |
136-
| `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog |
137-
| `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` |
138-
| `changelog_start_rev` | `str` | `None` | Start from a given git rev to generate the changelog |
139-
| `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] |
140-
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more][customization] |
141-
| `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. [See more][shortcuts] |
142-
143114
[version_files]: bump.md#version_files
144115
[tag_format]: bump.md#tag_format
145116
[bump_message]: bump.md#bump_message
117+
[major-version-zero]: bump.md#-major-version-zero
146118
[allow_abort]: check.md#allow-abort
147119
[additional-features]: https://github.com/tmbo/questionary#additional-features
148120
[customization]: customization.md

0 commit comments

Comments
 (0)