Skip to content

Commit d54209d

Browse files
woileLee-W
woile
authored and
Lee-W
committed
docs: add changelog rev_range and update bump and config
1 parent e94eae9 commit d54209d

File tree

2 files changed

+40
-22
lines changed

2 files changed

+40
-22
lines changed

‎docs/changelog.md

+24-11
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,28 @@ This command will generate a changelog following the committing rules establishe
66

77
```bash
88
$ cz changelog --help
9-
usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME]
10-
[--unreleased-version UNRELEASED_VERSION] [--incremental]
11-
[--start-rev START_REV]
9+
usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME] [--unreleased-version UNRELEASED_VERSION] [--incremental] [--start-rev START_REV]
10+
[rev_range]
11+
12+
positional arguments:
13+
rev_range generates changelog for the given version (e.g: 1.5.3) or version range (e.g: 1.5.3..1.7.9)
1214

1315
optional arguments:
1416
-h, --help show this help message and exit
1517
--dry-run show changelog to stdout
1618
--file-name FILE_NAME
1719
file name of changelog (default: 'CHANGELOG.md')
1820
--unreleased-version UNRELEASED_VERSION
19-
set the value for the new version (use the tag value),
20-
instead of using unreleased
21-
--incremental generates changelog from last created version, useful
22-
if the changelog has been manually modified
21+
set the value for the new version (use the tag value), instead of using unreleased
22+
--incremental generates changelog from last created version, useful if the changelog has been manually modified
2323
--start-rev START_REV
24-
start rev of the changelog.If not set, it will
25-
generate changelog from the start
24+
start rev of the changelog.If not set, it will generate changelog from the start
2625
```
2726
2827
### Examples
2928
29+
#### Generate full changelog
30+
3031
```bash
3132
cz changelog
3233
```
@@ -35,6 +36,18 @@ cz changelog
3536
cz ch
3637
```
3738
39+
#### Get the changelog for the given version
40+
41+
```bash
42+
cz changelog 0.3.0
43+
```
44+
45+
#### Get the changelog for the given version range
46+
47+
```bash
48+
cz changelog 0.3.0..0.4.0
49+
```
50+
3851
## Constrains
3952
4053
changelog generation is constrained only to **markdown** files.
@@ -66,15 +79,15 @@ and the following variables are expected:
6679
| `change_type` | The group where the commit belongs to, this is optional. Example: fix | `commit regex` |
6780
| `message`\* | Information extracted from the commit message | `commit regex` |
6881
| `scope` | Contextual information. Should be parsed using the regex from the message, it will be **bold** | `commit regex` |
69-
| `breaking` | Whether is a breaking change or not | `commit regex` |
82+
| `breaking` | Whether is a breaking change or not | `commit regex` |
7083
7184
- **required**: is the only one required to be parsed by the regex
7285
7386
## Configuration
7487
7588
### `unreleased_version`
7689
77-
There is usually an egg and chicken situation when automatically
90+
There is usually a chicken and egg situation when automatically
7891
bumping the version and creating the changelog.
7992
If you bump the version first, you have no changelog, you have to
8093
create it later, and it won't be included in

‎docs/config.md

+16-11
Original file line numberDiff line numberDiff line change
@@ -122,21 +122,26 @@ commitizen:
122122
123123
## Settings
124124
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-
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more][bump_message] |
132-
| `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog |
133-
| `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] |
134-
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more][customization] |
135-
| `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] |
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+
| `annotated_tag` | `bool` | `false` | Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight] |
133+
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more][bump_message] |
134+
| `changelog_file` | `str` | `CHANGELOG.md` | filename of exported changelog |
135+
| `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` |
136+
| `changelog_start_rev` | `str` | `None` | Start from a given git rev to generate the changelog |
137+
| `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] |
138+
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more][customization] |
139+
| `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] |
136140

137141
[version_files]: bump.md#version_files
138142
[tag_format]: bump.md#tag_format
139143
[bump_message]: bump.md#bump_message
140144
[additional-features]: https://github.com/tmbo/questionary#additional-features
141145
[customization]: customization.md
142146
[shortcuts]: customization.md#shortcut-keys
147+
[annotated-tags-vs-lightweight]: https://stackoverflow.com/a/11514139/2047185

0 commit comments

Comments
 (0)