### Interactive Configuration Example

Source: https://commitizen-tools.github.io/commitizen/commands/init

Initiate the Commitizen setup and follow the on-screen prompts to customize your project's commit message conventions, version management, and changelog generation.

```bash
# Start the initialization process
cz init

# Follow the interactive prompts to configure your project

```

--------------------------------

### Install a Third-Party Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/about

Use pip to install a new plugin package.

```sh
pip install package-name
```

--------------------------------

### Install cz-path Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-path

Install the cz-path plugin using pip.

```bash
pip install cz-path

```

--------------------------------

### Install Commitizen Globally with uv

Source: https://commitizen-tools.github.io/commitizen

Installs Commitizen globally using uv. Use this command to keep your global installation updated.

```bash
uv tool install commitizen

uv tool upgrade commitizen

```

--------------------------------

### PEP 440 Combined Pre-release and Development Examples

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Examples combining pre-release and development versions in PEP 440 format.

```text
1.0.0a1.dev0  # Development release 0 of alpha 1
1.0.0b2.dev1  # Development release 1 of beta 2

```

--------------------------------

### Example package.json

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

An example of a package.json file configured for npm version management, showing where Commitizen will manage the version.

```json
{
  "name": "my-package",
  "version": "0.1.0"
}

```

--------------------------------

### Example setup.py for Consistency Check

Source: https://commitizen-tools.github.io/commitizen/commands/bump

A Python setup.py file example that Commitizen checks for version consistency. Note the initial inconsistent version.

```python
from setuptools import setup

setup(..., version="1.0.5", ...)

```

--------------------------------

### PEP 440 Development Release Examples

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Examples of development releases in PEP 440 format.

```text
1.0.0.dev0  # Development release 0
1.0.0.dev1  # Development release 1

```

--------------------------------

### PEP 440 Pre-release Examples

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Examples of pre-release versions (alpha, beta, release candidate) in PEP 440 format.

```text
1.0.0a0  # Alpha release 0
1.0.0a1  # Alpha release 1
1.0.0b0  # Beta release 0
1.0.0rc0 # Release candidate 0
1.0.0rc1 # Release candidate 1

```

--------------------------------

### Install Commitizen Deno Provider

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/commitizen-deno-provider

Install the commitizen-deno-provider package using pip.

```bash
pip install commitizen-deno-provider

```

--------------------------------

### Interactive Commit Creation

Source: https://commitizen-tools.github.io/commitizen/commands/commit

Start the interactive commit creation process by running `cz commit` or its shortcut `cz c`. This guides you through generating a commit message based on configured rules.

```bash
cz commit

```

```bash
cz c

```

--------------------------------

### Set Up Development Environment

Source: https://commitizen-tools.github.io/commitizen/contributing/contributing

Install project dependencies and set up the development environment using uv.

```bash
uv sync --dev --frozen
```

--------------------------------

### Install cz-ai Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-ai

Install the cz-ai Commitizen plugin using pip.

```bash
pip install cz-ai

```

--------------------------------

### Example src/__version__.py for Consistency Check

Source: https://commitizen-tools.github.io/commitizen/commands/bump

A Python version file example that Commitizen checks for version consistency.

```python
__version__ = "1.21.0"

```

--------------------------------

### Install Commitizen with uv

Source: https://commitizen-tools.github.io/

Installs Commitizen globally using uv. Use this command to keep Commitizen updated.

```bash
uv tool install commitizen

uv tool upgrade commitizen
```

--------------------------------

### Initialize Commitizen Configuration

Source: https://commitizen-tools.github.io/

Runs the interactive setup to create a Commitizen configuration file.

```bash
cz init
```

--------------------------------

### Install GitHub JIRA Conventional Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/github-jira-conventional

Install the plugin using pip. Configuration and pre-commit instructions are available on the GitHub repository.

```bash
pip install cz-github-jira-conventional

```

--------------------------------

### Install Custom Provider Package

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

Install a custom Commitizen provider package using pip.

```bash
pip install my-commitizen-provider

```

--------------------------------

### Set Up Pre-commit Hooks

Source: https://commitizen-tools.github.io/commitizen/contributing/contributing

Install and configure pre-commit hooks to ensure code quality and consistency before committing.

```bash
uv run poe setup-pre-commit
```

--------------------------------

### Install prek

Source: https://commitizen-tools.github.io/commitizen/tutorials/auto_check

Install the prek framework using pip. This is a prerequisite for using the recommended method of automated commit message checking.

```bash
python -m pip install prek

```

--------------------------------

### Monorepo Directory Structure Example

Source: https://commitizen-tools.github.io/commitizen/tutorials/monorepo_guidance

Illustrates two common monorepo layouts with component directories.

```text
.
├── library-b
│   └── .cz.toml
└── library-z
    └── .cz.toml

```

```text
src
├── library-b
│   └── .cz.toml
└── library-z
    └── .cz.toml

```

--------------------------------

### Example Cargo.toml

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

An example of a Cargo.toml file configured for Cargo version management, showing where Commitizen will manage the version.

```toml
[package]
name = "my-crate"
version = "0.1.0"  # Managed by Commitizen

```

--------------------------------

### Install cz-conventional-gitmoji

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-conventional-gitmoji

Install the plugin using pip. This command is used to add the necessary package to your Python environment.

```bash
pip install cz-conventional-gitmoji

```

--------------------------------

### Install cz-emoji Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-emoji

Install the cz-emoji plugin using pip.

```bash
pip install cz-emoji

```

--------------------------------

### Example scenario for version_files configuration

Source: https://commitizen-tools.github.io/commitizen/config/bump

Demonstrates a comprehensive `version_files` configuration in `pyproject.toml` including direct file paths, glob patterns, and specific key targeting.

```toml
[tool.commitizen]
version_files = [
    "src/__version__.py",
    "packages/*/pyproject.toml:version",
    "setup.json:version",
]

```

--------------------------------

### Example composer.json

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

A sample composer.json file showing the 'version' field managed by Commitizen.

```json
{
  "name": "vendor/package",
  "version": "0.1.0"
}

```

--------------------------------

### Install Commitizen Globally with pipx

Source: https://commitizen-tools.github.io/commitizen

Installs Commitizen globally using pipx for isolated management. Use this command to keep your global installation updated.

```bash
pipx install commitizen

pipx upgrade commitizen

```

--------------------------------

### Install Custom Provider in Editable Mode

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

Install a custom Commitizen provider directly from the project source in editable mode.

```bash
pip install -e .

```

--------------------------------

### Install Commitizen Emoji Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/commitizen-emoji

Install the commitizen-emoji plugin using pip.

```bash
pip install commitizen-emoji

```

--------------------------------

### Example Unix Time Dev Release Tag

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

An example of a generated developmental release tag using Unix time.

```text
1.3.2.dev1696238452

```

--------------------------------

### Example Poetry pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

An example of a pyproject.toml file configured for Poetry version management, showing where Commitizen will manage the version.

```toml
[tool.poetry]
name = "my-package"
version = "0.1.0"  # Managed by Commitizen

```

--------------------------------

### Example PEP 621 pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

An example of a pyproject.toml file configured for PEP 621 version management, showing where Commitizen will manage the version.

```toml
[project]
name = "my-package"
version = "0.1.0"  # Managed by Commitizen

```

--------------------------------

### Install Pre-commit Hooks

Source: https://commitizen-tools.github.io/commitizen

Installs the configured pre-commit hooks for Commitizen. This command should be run after adding Commitizen to your pre-commit configuration.

```bash
prek install --hook-type commit-msg --hook-type pre-push

```

--------------------------------

### Install Commitizen with Homebrew

Source: https://commitizen-tools.github.io/

Installs Commitizen on macOS using the Homebrew package manager.

```bash
brew install commitizen
```

--------------------------------

### Install Commitizen with Homebrew

Source: https://commitizen-tools.github.io/commitizen

Installs Commitizen on macOS using the Homebrew package manager.

```bash
brew install commitizen

```

--------------------------------

### PEP 440 Standard Release Examples

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Examples of standard version numbers following the PEP 440 specification.

```text
0.9.0    # Initial development release
0.9.1    # Patch release
0.9.2    # Another patch release
0.9.10   # Tenth patch release
0.9.11   # Eleventh patch release
1.0.0    # First stable release
1.0.1    # Patch release after stable
1.1.0    # Minor feature release
2.0.0    # Major version release

```

--------------------------------

### Setup for JiraCommitizen Plugin

Source: https://commitizen-tools.github.io/commitizen/customization/python_class

Configures the `setup.py` file to package the custom Commitizen plugin, specifying its name, version, modules, and entry points.

```python
from setuptools import setup

setup(
    name="JiraCommitizen",
    version="0.1.0",
    py_modules=["cz_jira"],
    license="MIT",
    long_description="this is a long description",
    install_requires=["commitizen"],
    entry_points={"commitizen.plugin": ["cz_jira = cz_jira:JiraCz"]},
)

```

--------------------------------

### Example Commitizen Session with cz-path

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-path

Demonstrates an interactive Commitizen session using the cz-path plugin, showing how staged file paths influence prefix choices.

```bash
 $ git add .vscode/
 $ cz -n cz_path c
? Prefix: (Use arrow keys)
 » .vscode
   .vscode/
   project
   (empty)
? Prefix: .vscode
? Commit title: adjust settings

.vscode: adjust settings

[main 0000000] .vscode: adjust settings
 2 files changed, 1 insertion(+), 11 deletions(-)

Commit successful!

```

--------------------------------

### PEP621 Project Configuration

Source: https://commitizen-tools.github.io/commitizen/faq

Example of a pyproject.toml file with the [project] section as defined by PEP621.

```toml
[project]
name = "spam"
version = "2.5.1"


```

--------------------------------

### Run Commitizen Init Command

Source: https://commitizen-tools.github.io/commitizen/commands/init

Execute the `cz init` command to start the interactive configuration process for Commitizen in your project.

```bash
cz init

```

--------------------------------

### Install Pre-commit Hooks

Source: https://commitizen-tools.github.io/

Installs the configured pre-commit hooks, including Commitizen's commit message validation and pre-push checks.

```bash
prek install --hook-type commit-msg --hook-type pre-push
```

--------------------------------

### Good Subject Line Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Examples of concise and clear subject lines for commit messages, summarizing the change effectively.

```markdown
```
fix(commands): handle missing user input gracefully
feat(api): add pagination support

```
```

--------------------------------

### CircleCI Dev Release Example

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

Uses the CIRCLE_BUILD_NUM environment variable to create a unique developmental release tag in CircleCI.

```bash
--devrelease ${CIRCLE_BUILD_NUM}

```

--------------------------------

### Install cz-legacy Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-legacy

Install the cz-legacy Python package using pip. This command is used to add the plugin to your project's environment.

```bash
pip install cz_legacy

```

--------------------------------

### Commitizen Configuration in .cz.yaml

Source: https://commitizen-tools.github.io/commitizen/config/configuration_file

Example of a Commitizen configuration file in YAML format. This mirrors the JSON example, showing equivalent settings for commit convention, version management, changelog, and customization.

```yaml
commitizen:
  name: cz_conventional_commits
  version: "0.1.0"
  version_provider: commitizen
  version_scheme: pep440
  version_files:
    - src/__version__.py
    - pyproject.toml:version
  tag_format: "$version"
  update_changelog_on_bump: true
  changelog_file: CHANGELOG.md
  changelog_incremental: false
  bump_message: "bump: version $current_version → $new_version"
  gpg_sign: false
  annotated_tag: false
  major_version_zero: false
  prerelease_offset: 0
  retry_after_failure: false
  allow_abort: false
  message_length_limit: 0
  allowed_prefixes:
    - Merge
    - Revert
    - Pull request
    - fixup!
    - squash!
    - amend!
  breaking_change_exclamation_in_title: false
  use_shortcuts: false
  pre_bump_hooks: []
  post_bump_hooks: []
  encoding: utf-8
  style:
    - - qmark
      - fg:#ff9d00 bold
    - - question
      - bold
    - - answer
      - fg:#ff9d00 bold
    - - pointer
      - fg:#ff9d00 bold
    - - highlighted
      - fg:#ff9d00 bold
    - - selected
      - fg:#cc5454
    - - separator
      - fg:#cc5454
    - - instruction
      - ""
    - - text
      - ""
    - - disabled
      - fg:#858585 italic

```

--------------------------------

### Install Conventional JIRA Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/conventional-jira

Install the Conventional JIRA plugin using pip. This command adds the plugin to your Python environment.

```bash
pip install conventional-JIRA

```

--------------------------------

### Example GitHub Dev Release Tag

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

An example of a generated developmental release tag using GitHub's run ID.

```text
1.3.2.dev6048584598

```

--------------------------------

### Install Commitizen with uv (project-specific)

Source: https://commitizen-tools.github.io/

Adds Commitizen as a development dependency to a project using uv.

```bash
uv add --dev commitizen
```

--------------------------------

### Example pyproject.toml Configuration for Consistency Check

Source: https://commitizen-tools.github.io/commitizen/commands/bump

This TOML snippet shows the configuration for Commitizen, specifying the main version and the files to check for version consistency.

```toml
[tool.commitizen]
version = "1.21.0"
version_files = [
    "src/__version__.py",
    "setup.py",
]

```

--------------------------------

### Install Git Hooks for Commitizen

Source: https://commitizen-tools.github.io/commitizen/tutorials/auto_prepare_commit_message

Download and make executable the `prepare-commit-msg` and `post-commit` hooks from the Commitizen repository. These hooks automate the commit message preparation and handling.

```bash
wget -O .git/hooks/prepare-commit-msg https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/prepare-commit-msg.py
chmod +x .git/hooks/prepare-commit-msg
wget -O .git/hooks/post-commit https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/post-commit.py
chmod +x .git/hooks/post-commit
```

--------------------------------

### Example CircleCI Dev Release Tag

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

An example of a generated developmental release tag using CircleCI's build number.

```text
1.3.2.dev2478

```

--------------------------------

### Example pyproject.toml for Local Version Bump

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Configuration showing a version string with a local component, which can be bumped using the `--local-version` flag.

```toml
[tool.commitizen]
version = "5.3.5+0.1.0"

```

--------------------------------

### GitHub Dev Release Example

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

Uses the GITHUB_RUN_ID environment variable to create a unique developmental release tag in GitHub Actions.

```bash
--devrelease ${GITHUB_RUN_ID}

```

--------------------------------

### CI/CD Pipeline Example with --no-raise

Source: https://commitizen-tools.github.io/commitizen/exit_codes

Example of using `--no-raise` in a GitHub Actions workflow to allow the pipeline to continue even if no version bump is needed. The `|| true` ensures the step itself doesn't fail.

```yaml
# .github/workflows/release.yml
- name: Bump version
  run: |
    cz -nr NO_INCREMENT bump || true
    # Continue even if no version bump is needed
```

--------------------------------

### Configure Starting Revision for Changelog

Source: https://commitizen-tools.github.io/commitizen/commands/changelog

Set the default starting revision for changelog generation in the Commitizen configuration file using the `changelog_start_rev` key.

```toml
[tool.commitizen]
# ...
changelog_start_rev = "v0.2.0"

```

--------------------------------

### Good Commit Message Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

A collection of well-formatted commit messages demonstrating best practices for subject lines and scopes.

```markdown
`fix(commands): bump error when no user provided`
```

```markdown
`feat(api): add pagination to user list endpoint`
```

```markdown
`docs: update installation instructions`
```

```markdown
`refactor(parser): simplify token extraction logic`
```

--------------------------------

### Get Help for Commitizen Commands

Source: https://commitizen-tools.github.io/commitizen

Use the --help flag with any Commitizen command to get detailed usage information. This is useful for understanding command-specific options and arguments.

```bash
cz commit --help
cz bump --help
cz changelog --help

```

--------------------------------

### Unix Time Dev Release Example

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

Uses the current Unix time to create a developmental release tag. This may cause collisions if builds occur in the same second.

```bash
--devrelease $(date +%s)

```

--------------------------------

### Example Commit Message for library-b Changelog

Source: https://commitizen-tools.github.io/commitizen/tutorials/monorepo_guidance

Demonstrates a commit message that would be included in the 'library-b' changelog due to matching the configured 'changelog_pattern'.

```git
fix(library-b): Some awesome message

```

--------------------------------

### Install Commitizen Project-Specific with uv

Source: https://commitizen-tools.github.io/commitizen

Adds Commitizen as a development dependency to a project managed by uv.

```bash
uv add --dev commitizen

```

--------------------------------

### Specify Starting Revision for Changelog

Source: https://commitizen-tools.github.io/commitizen/commands/changelog

Generate the changelog starting from a specific Git revision using the `--start-rev` parameter. This excludes commits made before the specified revision.

```bash
cz changelog --start-rev="v0.2.0"

```

--------------------------------

### Commitizen Configuration in .cz.json

Source: https://commitizen-tools.github.io/commitizen/config/configuration_file

Example of a Commitizen configuration file in JSON format. This includes settings for commit convention, version management, changelog, and customization.

```json
{
  "commitizen": {
    "name": "cz_conventional_commits",
    "version": "0.1.0",
    "version_provider": "commitizen",
    "version_scheme": "pep440",
    "version_files": [
      "src/__version__.py",
      "pyproject.toml:version"
    ],
    "tag_format": "$version",
    "update_changelog_on_bump": true,
    "changelog_file": "CHANGELOG.md",
    "changelog_incremental": false,
    "bump_message": "bump: version $current_version → $new_version",
    "gpg_sign": false,
    "annotated_tag": false,
    "major_version_zero": false,
    "prerelease_offset": 0,
    "retry_after_failure": false,
    "allow_abort": false,
    "message_length_limit": 0,
    "allowed_prefixes": [
      "Merge",
      "Revert",
      "Pull request",
      "fixup!",
      "squash!",
      "amend!"
    ],
    "breaking_change_exclamation_in_title": false,
    "use_shortcuts": false,
    "pre_bump_hooks": [],
    "post_bump_hooks": [],
    "encoding": "utf-8",
    "style": [
      ["qmark", "fg:#ff9d00 bold"],
      ["question", "bold"],
      ["answer", "fg:#ff9d00 bold"],
      ["pointer", "fg:#ff9d00 bold"],
      ["highlighted", "fg:#ff9d00 bold"],
      ["selected", "fg:#cc5454"],
      ["separator", "fg:#cc5454"],
      ["instruction", ""],
      ["text", ""],
      ["disabled", "fg:#858585 italic"]
    ]
  }
}
```

--------------------------------

### Scope Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Use an optional scope to specify the part of the codebase affected by the commit.

```markdown
```
feat(parser): add support for JSON arrays
fix(api): handle null response gracefully

```
```

--------------------------------

### Create a Custom Commitizen Plugin

Source: https://commitizen-tools.github.io/commitizen/customization/python_class

Use `cookiecutter` to automate the setup for creating a new commitizen plugin based on a Python class.

```bash
cookiecutter gh:commitizen-tools/commitizen_cz_template

```

--------------------------------

### Get Project Version

Source: https://commitizen-tools.github.io/commitizen/commands/version

Retrieves the version of the current project. This is useful for understanding the project's current release status.

```bash
cz version --project
```

--------------------------------

### Install Commitizen with Poetry

Source: https://commitizen-tools.github.io/

Adds Commitizen as a development dependency to a Poetry-managed project. The command varies slightly for Poetry versions.

```bash
# For Poetry >= 1.2.0
poetry add commitizen --group dev

# For Poetry < 1.2.0
poetry add commitizen --dev
```

--------------------------------

### Create and Prepare commit-msg Hook File

Source: https://commitizen-tools.github.io/commitizen/tutorials/auto_check

Manually create the commit-msg hook file in the .git/hooks directory and make it executable. This is the first step for manual Git hook installation.

```bash
cd .git/hooks
touch commit-msg
chmod +x commit-msg

```

--------------------------------

### Example: pyproject.toml configuration for Commitizen

Source: https://commitizen-tools.github.io/commitizen/config/option

This snippet shows how to configure the Commitizen name and use_shortcuts option in a pyproject.toml file. It sets the commit convention to 'cz_conventional_commits' and enables keyboard shortcuts for prompt selections.

```toml
[tool.commitizen]
name = "cz_conventional_commits"
use_shortcuts = true

```

--------------------------------

### Commitizen Configuration in pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/configuration_file

Example of a Commitizen configuration within the `[tool.commitizen]` section of a `pyproject.toml` file. This is recommended for Python projects to centralize configuration.

```toml
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
version_provider = "commitizen"
version_scheme = "pep440"
version_files = [
    "src/__version__.py",
    "pyproject.toml:version"
]
tag_format = "$version"
update_changelog_on_bump = true
changelog_file = "CHANGELOG.md"
changelog_incremental = false
bump_message = "bump: version $current_version → $new_version"
gpg_sign = false
annotated_tag = false
major_version_zero = false
prerelease_offset = 0
retry_after_failure = false
allow_abort = false
message_length_limit = 0
allowed_prefixes = [
    "Merge",
    "Revert",
    "Pull request",
    "fixup!",
    "squash!",
    "amend!"
]
breaking_change_exclamation_in_title = false
use_shortcuts = false
pre_bump_hooks = []
post_bump_hooks = []
encoding = "utf-8"


```

--------------------------------

### Install Commitizen with conda

Source: https://commitizen-tools.github.io/

Installs Commitizen within a conda environment from the conda-forge channel.

```bash
conda install -c conda-forge commitizen
```

--------------------------------

### Update version in setup.json

Source: https://commitizen-tools.github.io/commitizen/config/bump

Shows the before and after state of a `setup.json` file after a version bump, illustrating how Commitizen updates the specified 'version' field.

```json
{
    "name": "magictool",
    "version": "1.2.3",
    "dependencies": {
        "lodash": "1.2.3"
    }
}

```

```diff
{
    "name": "magictool",
-   "version": "1.2.3",
+   "version": "2.0.0",
    "dependencies": {
        "lodash": "1.2.3"
    }
}

```

--------------------------------

### Get Project Version and Preview Changelog

Source: https://commitizen-tools.github.io/commitizen

Retrieves the current project version and previews potential changelog updates without making changes. Useful for automation scripts.

```bash
# Get your project's version (instead of Commitizen's version)
cz version -p
# Preview changelog changes
cz changelog --dry-run "$(cz version -p)"

```

--------------------------------

### Build and Preview Docs Locally

Source: https://commitizen-tools.github.io/commitizen/contributing/contributing_tldr

Builds and previews the project documentation locally. Essential for verifying documentation changes.

```bash
uv run poe doc
```

--------------------------------

### Register Custom Provider in setup.py

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

Register a custom Commitizen provider using the 'commitizen.provider' entry point in setup.py for legacy projects.

```python
from setuptools import setup

setup(
    name="my-commitizen-provider",
    version="0.1.0",
    py_modules=["my_provider"],
    install_requires=["commitizen"],
    entry_points={
        "commitizen.provider": [
            "my-provider = my_provider:MyProvider",
        ]
    },
)

```

--------------------------------

### Install Commitizen with pip

Source: https://commitizen-tools.github.io/

Installs or updates Commitizen within a Python project using pip.

```bash
pip install -U commitizen
```

--------------------------------

### Install Commitizen Project-Specific with Poetry

Source: https://commitizen-tools.github.io/commitizen

Adds Commitizen as a development dependency to a Poetry-managed project. Use the appropriate group flag based on your Poetry version.

```bash
# For Poetry >= 1.2.0
poetry add commitizen --group dev

# For Poetry < 1.2.0
poetry add commitizen --dev

```

--------------------------------

### Avoided Imperative Mood Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Examples of commit messages not using the imperative mood, which should be avoided.

```markdown
```
feat: added user authentication
fix: resolved memory leak in parser

```
```

--------------------------------

### Generate Changelog for a Version Range

Source: https://commitizen-tools.github.io/commitizen/commands/changelog

Generate changelog entries for a specific range of versions by providing the start and end version numbers, separated by '..', along with the `--dry-run` flag for preview.

```bash
# Get the changelog for the given version range
cz changelog 0.3.0..0.4.0 --dry-run

```

--------------------------------

### Use cz-conventional-gitmoji for Commits

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-conventional-gitmoji

Initiate a commit using the Commitizen CLI with the cz_gitmoji plugin. This command starts the commit message creation process with Gitmoji support.

```bash
cz --name cz_gitmoji commit

```

--------------------------------

### Avoided Subject Line Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Examples of unclear or overly broad subject lines that should be avoided.

```markdown
```
fix: stuff
feat: commit command introduced

```
```

--------------------------------

### Configure Commitizen for Deno Provider

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/commitizen-deno-provider

Add 'deno-provider' to your Commitizen configuration file to enable version management for Deno projects. This example shows configuration for a .cz.yaml file.

```yaml
---
commitizen:
  major_version_zero: true
  name: cz_conventional_commits
  tag_format: $version
  update_changelog_on_bump: true
  version_provider: deno-provider
  version_scheme: semver

```

--------------------------------

### Install Commitizen Project-Specific with conda

Source: https://commitizen-tools.github.io/commitizen

Installs Commitizen within a specific Python project using conda.

```bash
conda install -c conda-forge commitizen

```

--------------------------------

### Generate Documentation Screenshots

Source: https://commitizen-tools.github.io/commitizen/contributing/contributing

Generate screenshots for CLI help documentation.

```bash
uv run poe doc:screenshots
```

--------------------------------

### Poor Commit Message Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Examples of poorly written commit messages that lack clarity and conciseness.

```markdown
`fix: stuff`
```

```markdown
`feat: commit command introduced`
```

```markdown
`docs: changes`
```

```markdown
`refactor: code cleanup`
```

--------------------------------

### Install Commitizen Project-Specific with pip

Source: https://commitizen-tools.github.io/commitizen

Installs or updates Commitizen within a specific Python project using pip.

```bash
pip install -U commitizen

```

--------------------------------

### Migrating Legacy Commitizen Plugin to Entrypoint

Source: https://commitizen-tools.github.io/commitizen/customization/python_class

Demonstrates removing the `discover_this` attribute and exposing the plugin class via `setuptools` entry points for the new Commitizen plugin format.

```python
from commitizen.cz.base import BaseCommitizen


class PluginCz(BaseCommitizen):
    ...
```

```python
from setuptools import setup

setup(
    name="MyPlugin",
    version="0.1.0",
    py_modules=["cz_plugin"],
    entry_points={"commitizen.plugin": ["plugin = cz_plugin:PluginCz"]},
    ...,
)
```

--------------------------------

### Set Prerelease Offset

Source: https://commitizen-tools.github.io/commitizen/config/bump

Configure `prerelease_offset` to specify the starting number for prereleases, useful when '0' is not a valid starting point.

```toml
[tool.commitizen]
prerelease_offset = 1

```

--------------------------------

### Manually Update Version in setup.py

Source: https://commitizen-tools.github.io/commitizen/commands/bump

After restoring files, manually update the version in files like `setup.py` to match the intended version before re-running the bump command.

```diff
from setuptools import setup

- setup(..., version="1.0.5", ...)
+ setup(..., version="1.21.0", ...)

```

--------------------------------

### Configure SCM Version Provider

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

Use the 'scm' provider to fetch version from Git tags. This provider is read-only and does not write versions back to files, making it suitable for projects managed by tools like setuptools-scm.

```toml
[tool.commitizen]
version_provider = "scm"
# No version field needed - it's read from Git tags

```

--------------------------------

### Use cz-ai Plugin

Source: https://commitizen-tools.github.io/commitizen/third-party-plugins/cz-ai

Initiate the commit process using the cz-ai plugin with the Commitizen CLI.

```bash
cz --name cz_ai commit

```

--------------------------------

### Specify Configuration File Path

Source: https://commitizen-tools.github.io/commitizen/config/configuration_file

Use the --config option to explicitly point to a configuration file, bypassing the default search order. This is useful when the configuration file is not in the project root.

```bash
cz --config <PATH> <command>

```

--------------------------------

### Install Commitizen Git Hook with prek

Source: https://commitizen-tools.github.io/commitizen/tutorials/auto_check

Install the commitizen hook into your Git repository using the prek command. This command registers the hook to run during the commit-msg stage.

```bash
prek install --hook-type commit-msg

```

--------------------------------

### Example Commit Validation Failure Output

Source: https://commitizen-tools.github.io/commitizen/tutorials/auto_check

This is an example of the error output you might see when a commit message fails Commitizen's validation. It shows the failed commit and the expected pattern.

```text
commit validation: failed!
please enter a commit message in the commitizen format.
commit "abc123": "invalid message"
pattern: ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .{1,}

```

--------------------------------

### Set Version Scheme via Command Line

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Use the `--version-scheme` flag to specify the versioning scheme when bumping.

```bash
cz bump --version-scheme semver2

```

--------------------------------

### Install Commitizen with pdm

Source: https://commitizen-tools.github.io/

Adds Commitizen as a development dependency to a PDM-managed project.

```bash
pdm add -d commitizen
```

--------------------------------

### Install Commitizen Project-Specific with pdm

Source: https://commitizen-tools.github.io/commitizen

Adds Commitizen as a development dependency to a PDM-managed project.

```bash
pdm add -d commitizen

```

--------------------------------

### Enable GPG Signing for Tags

Source: https://commitizen-tools.github.io/commitizen/config/bump

Set `gpg_sign` to `true` to enable GPG signing for release tags.

```toml
[tool.commitizen]
gpg_sign = true

```

--------------------------------

### Outputting Next Version with --get-next

Source: https://commitizen-tools.github.io/commitizen/commands/bump

The `--get-next` flag outputs only the next version number without additional details. Useful for CI/CD pipelines.

```bash
# outputs 1.0.1 if the current version is 1.0.0 and the increment is PATCH
cz bump --get-next
```

--------------------------------

### Configure Pre-Bump Hooks

Source: https://commitizen-tools.github.io/commitizen/config/bump

Use `pre_bump_hooks` to specify commands that run after version files are updated but before committing and tagging.

```toml
[tool.commitizen]
pre_bump_hooks = [
  "scripts/generate_documentation.sh"
]

```

--------------------------------

### Configure version_scheme in pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/bump

Define the versioning format to be used. Options are 'pep440' (default for Python), 'semver2' (recommended for non-Python), and 'semver' (for older semver v1).

```toml
[tool.commitizen]
version_scheme = "semver2"

```

--------------------------------

### Imperative Mood Examples

Source: https://commitizen-tools.github.io/commitizen/tutorials/writing_commits

Commit messages written in the imperative mood, as if completing the sentence 'If applied, this commit will...'.

```markdown
```
feat: add user authentication
fix: resolve memory leak in parser

```
```

--------------------------------

### Configure version_provider in pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/bump

Set the mechanism for reading and writing version information. Options include 'commitizen', 'scm', 'pep621', 'poetry', 'uv', 'cargo', 'npm', and 'composer'.

```toml
[tool.commitizen]
version_provider = "pep621"

```

--------------------------------

### Generate Full Changelog

Source: https://commitizen-tools.github.io/commitizen/commands/changelog

Use the `cz changelog` command to generate the complete changelog from the beginning. The alias `cz ch` can also be used for brevity.

```bash
# Generate full changelog
cz changelog

# Or use the alias
cz ch

```

--------------------------------

### Configure version_files with patterns in pyproject.toml

Source: https://commitizen-tools.github.io/commitizen/config/bump

Use patterns to specify files and the exact key within those files to update version information. This allows for more granular control over version updates in different file types.

```toml
[tool.commitizen]
version_files = [
    "packages/*/pyproject.toml:version",
    "setup.json:version",
]

```

--------------------------------

### Configure Post-Bump Hooks

Source: https://commitizen-tools.github.io/commitizen/config/bump

Use `post_bump_hooks` to specify commands that run after the release has been committed and tagged.

```toml
[tool.commitizen]
post_bump_hooks = [
  "scripts/slack_notification.sh"
]

```

--------------------------------

### Custom Version Provider Implementation

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

A Python class extending VersionProvider to read/write from a VERSION file.

```python
from pathlib import Path
from commitizen.providers import VersionProvider


class MyProvider(VersionProvider):
    """
    Custom version provider that reads/writes from a VERSION file.
    """

    def get_version(self) -> str:
        """Read version from VERSION file."""
        version_file = Path("VERSION")
        if not version_file.is_file():
            return "0.0.0"
        return version_file.read_text().strip()

    def set_version(self, version: str) -> None:
        """Write version to VERSION file."""
        version_file = Path("VERSION")
        version_file.write_text(f"{version}\n")

```

--------------------------------

### Enable Global Bash Completion for Commitizen

Source: https://commitizen-tools.github.io/

Use this command to enable global completion for all Python applications, including Commitizen, if Commitizen was installed globally.

```bash
sudo activate-global-python-argcomplete
```

--------------------------------

### Dev Release Format

Source: https://commitizen-tools.github.io/commitizen/tutorials/dev_releases

The standard format for a developmental release as defined by PEP440.

```text
X.Y.devN

```

--------------------------------

### Get Specific Project Version Component

Source: https://commitizen-tools.github.io/commitizen/commands/version

Retrieves only the major component of the current project's version. Requires the --project flag to be set.

```bash
cz version --project --major
```

--------------------------------

### Configure Composer Version Provider

Source: https://commitizen-tools.github.io/commitizen/config/version_provider

Set the version provider to 'composer' in your Commitizen configuration.

```toml
[tool.commitizen]
version_provider = "composer"

```

--------------------------------

### Adding Build Metadata to Version

Source: https://commitizen-tools.github.io/commitizen/commands/bump

Use the `--build-metadata` option to append custom metadata to the version string. This is useful for labeling releases.

```bash
# creates a version like `1.1.2+yourmetadata`.
cz bump --build-metadata yourmetadata
```