Deploying to gh-pages from @ 048fa47 🚀

Author: Lee-W

commands/bump/index.md

@@ -0,0 +1,187 @@
+## About
+
+Generates a changelog following the committing rules established.
+
+When changelog generation is triggered by `cz bump --allow-no-commit` (with `--changelog` or `update_changelog_on_bump = true`), Commitizen still creates a release entry even when no commits are found in the selected revision range.
+
+Tip
+
+To create the changelog automatically on bump, add the setting [update_changelog_on_bump](https://commitizen-tools.github.io/commitizen/config/bump/#update_changelog_on_bump)
+
+```
+[tool.commitizen]
+update_changelog_on_bump = true
+```
+
+## Usage
+
+## Examples
+
+```
+# Generate full changelog
+cz changelog
+
+# Or use the alias
+cz ch
+
+# Get the changelog for the given version
+cz changelog 0.3.0 --dry-run
+
+# Get the changelog for the given version range
+cz changelog 0.3.0..0.4.0 --dry-run
+```
+
+## Constraints
+
+Changelog generation is constrained only to **markdown** files.
+
+## Description
+
+These are the variables used by the changelog generator.
+
+```
+# <version> (<date>)
+
+## <change_type>
+
+- **<scope>**: <message>
+```
+
+Creates a full block like above per version found in the tags, and a list of the commits found. The `change_type` and `scope` are optional and don't need to be provided, but if your regex parses them, they will be rendered.
+
+The format followed by the changelog is from [keep a changelog](https://keepachangelog.com/) and the following variables are expected:
+
+| Variable      | Description                                                                                    | Source         |
+| ------------- | ---------------------------------------------------------------------------------------------- | -------------- |
+| `version`     | Version number which should follow [semver](https://semver.org/)                               | `tags`         |
+| `date`        | Date when the tag was created                                                                  | `tags`         |
+| `change_type` | The group where the commit belongs to, this is optional. Example: fix                          | `commit regex` |
+| `message`     | Information extracted from the commit message                                                  | `commit regex` |
+| `scope`       | Contextual information. Should be parsed using the regex from the message, it will be **bold** | `commit regex` |
+| `breaking`    | Whether it is a breaking change or not                                                         | `commit regex` |
+
+Note
+
+`message` is the only variable required to be parsed by the regex.
+
+## Command line options
+
+### `--extras`
+
+Provide your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter.
+
+```
+cz changelog --extra key=value -e short="quoted value"
+```
+
+### `--file-name`
+
+Specify the name of the output file. Note that changelog generation only works with Markdown files.
+
+```
+cz changelog --file-name="CHANGES.md"
+```
+
+This value can be updated in the configuration file with the key `changelog_file` under `tool.commitizen`.
+
+```
+[tool.commitizen]
+# ...
+changelog_file = "CHANGES.md"
+```
+
+### `--incremental`
+
+Build from the latest version found in changelog.
+
+Benefits:
+
+- Useful if you have an existing changelog and want to use commitizen to extend it.
+- Update unreleased area
+- Allows users to manually edit the changelog without it being completely rewritten.
+
+```
+cz changelog --incremental
+```
+
+This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen`.
+
+```
+[tool.commitizen]
+# ...
+changelog_incremental = true
+```
+
+### `--start-rev`
+
+Start from a given git rev to generate the changelog. Commits before that rev will not be considered. This is especially useful for long-running projects adopting conventional commits, where old commit messages might fail to be parsed for changelog generation.
+
+```
+cz changelog --start-rev="v0.2.0"
+```
+
+This value can be set in the configuration file with the key `changelog_start_rev` under `tool.commitizen`
+
+```
+[tool.commitizen]
+# ...
+changelog_start_rev = "v0.2.0"
+```
+
+### `--merge-prerelease`
+
+Collects changes from prereleases into the next non-prerelease version. If you have a prerelease version followed by a normal release, the changelog will show the prerelease changes as part of the normal release. If not set, prereleases will be included as separate entries in the changelog.
+
+```
+cz changelog --merge-prerelease
+```
+
+This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tool.commitizen`
+
+```
+[tool.commitizen]
+# ...
+changelog_merge_prerelease = true
+```
+
+### `--template`
+
+Provide your own changelog Jinja template by using the `template` settings or the `--template` parameter.
+
+```
+cz changelog --template="path/to/template.j2"
+```
+
+### `--unreleased-version`
+
+There is usually a chicken-and-egg situation when automatically bumping the version and creating the changelog:
+
+- If you bump the version first, you have no changelog yet, and it won't be included in the release of the created version.
+- If you create the changelog before bumping the version, you usually don't have the latest tag, and the *Unreleased* title appears.
+
+By using `--unreleased-version`, you can prevent this situation.
+
+Before bumping you can run:
+
+```
+cz changelog --unreleased-version="v1.0.0"
+```
+
+Remember to use the tag format instead of the raw version number.
+
+For example, if your tag format includes a `v` prefix (e.g., `v1.0.0`), use that format. If your tag is the same as the raw version (e.g., `1.0.0`), use the raw version.
+
+Alternatively, you can directly bump the version and create the changelog by running:
+
+```
+cz bump --changelog
+```
+
+## Hooks
+
+Supported hook methods:
+
+- Per parsed message: Useful to add links to commits or issues
+- End of changelog generation: Useful to send Slack or chat messages, or notify another department
+
+Read more about hooks in the [customization page](https://commitizen-tools.github.io/commitizen/customization/config_file/index.md)

commands/changelog/index.md

@@ -0,0 +1,168 @@
+This feature checks whether a string or a range of git commits follows the given committing rules. Comments in git messages will be ignored.
+
+To set up an automatic check before every git commit, please refer to [Automatically check message before commit](https://commitizen-tools.github.io/commitizen/tutorials/auto_check/index.md).
+
+## Usage
+
+More specifically, there are three mutually exclusive ways to use `cz check`:
+
+- Validate a range of git commit messages with `--rev-range`
+- Validate a given string with `--message` or by piping the message to it
+- Validate a commit message from a file with `--commit-msg-file`
+
+### Use `cz check` to validate a commit message before committing
+
+#### Option 1: use `--message` to check a given string:
+
+```
+cz check --message <message_to_be_checked>
+```
+
+#### Option 2: pipe the message to `cz check`:
+
+```
+echo <message_to_be_checked> | cz check
+```
+
+#### Option 3: use `--commit-msg-file` to read the commit message from a file
+
+```
+cz check --commit-msg-file /path/to/file.txt
+```
+
+## Command Line Options
+
+### `--rev-range`
+
+Test if a given range of commits in the git log passes `cz check`.
+
+```
+cz check --rev-range REV_RANGE
+```
+
+For more information on `REV_RANGE`, check the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_commit_ranges).
+
+#### Use cases
+
+1. Validate the latest 3 commit messages:
+
+   ```
+   cz check --rev-range HEAD~3..HEAD
+   # or
+   cz check --rev-range HEAD~3..
+   # or
+   cz check --rev-range HEAD~~~..
+   ```
+
+1. Validate all git commit messages on some branch up to HEAD:
+
+   ```
+   cz check --rev-range <branch_name>..HEAD
+   ```
+
+   For example, to check all git commit messages on `main` branch up to HEAD:
+
+   ```
+   cz check --rev-range main..HEAD
+   ```
+
+   or if your project still uses `master` branch:
+
+   ```
+   cz check --rev-range master..HEAD
+   ```
+
+   Default branch
+
+   Usually the default branch is `main` or `master`. You can check the default branch by running `cz check --use-default-range`.
+
+1. Validate all git commit messages starting from when you first implemented commit message linting:
+
+   **(Why this is useful?)** Let's say you decided to enforce commit message today. However, it is impractical to `git rebase` all your previous commits. `--rev-range` helps you skip commits before you first implemented commit message linting by using a specific commit hash.
+
+   ```
+   cz check --rev-range <first_commit_sha>..HEAD
+   ```
+
+### `--use-default-range`
+
+Equivalent to `--rev-range <default_branch>..HEAD`.
+
+```
+cz check --use-default-range
+# or
+cz check -d
+```
+
+### `--message`
+
+Test if a given string passes `cz check`.
+
+```
+cz check --message <message_to_be_checked>
+```
+
+### `--commit-msg-file`
+
+Test if a given file contains a commit message that passes `cz check`.
+
+```
+cz check --commit-msg-file <path_to_file_containing_message_to_be_checked>
+```
+
+This can be useful when cooperating with git hooks. Please check [Automatically check message before commit](https://commitizen-tools.github.io/commitizen/tutorials/auto_check/index.md) for more detailed examples.
+
+### `--allow-abort`
+
+Example:
+
+```
+cz check --message <message_to_be_checked> --allow-abort
+```
+
+Empty commit messages typically instruct Git to abort a commit, so you can pass `--allow-abort` to permit them. Since `git commit` accepts the `--allow-empty-message` flag (primarily for wrapper scripts), you may wish to disallow such commits in CI. `--allow-abort` may be used in conjunction with any of the other options.
+
+### `--allowed-prefixes`
+
+Skip validation for commit messages that start with the specified prefixes.
+
+If not set, commit messages starting with the following prefixes are ignored by `cz check`:
+
+- `Merge`
+- `Revert`
+- `Pull request`
+- `fixup!`
+- `squash!`
+- `amend!`
+
+```
+cz check --message <message_to_be_checked> --allowed-prefixes 'Merge' 'Revert' 'Custom Prefix'
+```
+
+For example,
+
+```
+# The following message passes the check because it starts with 'Merge'
+cz check --message "Merge branch 'main' into feature/new-feature" --allowed-prefixes 'Merge'
+
+# The following fails
+cz check --message "Merge branch 'main' into feature/new-feature" --allowed-prefixes 'aaa'
+```
+
+### `--message-length-limit`
+
+Restrict the length of **the first line** of the commit message.
+
+```
+# The following passes
+cz check --message "docs(check): fix grammar issues" -l 80
+
+# The following fails
+cz check --message "docs:very long long long long message with many words" -l 3
+```
+
+By default, the limit is set to `0`, which means no limit on the length.
+
+Note
+
+Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject, while the body and the footer are not counted.