commitizen-tools · Lee-W · Aug 6, 2025 · Jun 10, 2025 · Jun 10, 2025 · Jun 10, 2025
@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+  workflow_dispatch:
 
 jobs:
   update-cli-screenshots:
@@ -58,21 +59,19 @@ jobs:
           python -m pip install -U pip poetry poethepoet
           poetry --version
           poetry install --no-root --only documentation
-      - name: Build docs
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          poetry doc:build
       - name: Generate Sponsors 💖
         uses: JamesIves/github-sponsors-readme-action@v1
         with:
           token: ${{ secrets.PERSONAL_ACCESS_TOKEN_FOR_ORG }}
           file: "docs/README.md"
-      - name: Push doc to Github Page
-        uses: peaceiris/actions-gh-pages@v4
+          organization: true
+      - name: Build docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          poetry doc:build
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
-          personal_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          publish_branch: gh-pages
-          publish_dir: ./site
-          user_name: "github-actions[bot]"
-          user_email: "github-actions[bot]@users.noreply.github.com"
+          folder: ./site # The folder the action should deploy.
+          branch: gh-pages
@@ -24,7 +24,7 @@ jobs:
         run: |
           echo "project_version=$(cz version --project)" >> $GITHUB_ENV
       - name: Update Homebrew formula
-        uses: dawidd6/action-homebrew-bump-formula@v4
+        uses: dawidd6/action-homebrew-bump-formula@v5
         with:
           token: ${{secrets.PERSONAL_ACCESS_TOKEN}}
           formula: commitizen

@@ -236,7 +236,7 @@ def _ask_version_provider(self) -> str:
             "npm": "npm: Get and set version from package.json:project.version field",
             "pep621": "pep621: Get and set version from pyproject.toml:project.version field",
             "poetry": "poetry: Get and set version from pyproject.toml:tool.poetry.version field",
-            "uv": "uv: Get and Get and set version from pyproject.toml and uv.lock",
+            "uv": "uv: Get and set version from pyproject.toml and uv.lock",
             "scm": "scm: Fetch the version from git and does not need to set it back",
         }
 

@@ -8,9 +8,6 @@
 
 from commitizen.question import CzQuestion
 
-# Type
-Questions = Iterable[MutableMapping[str, Any]]  # TODO: deprecate this?
-
 
 class CzSettings(TypedDict, total=False):
     bump_pattern: str
@@ -161,6 +158,10 @@ def get_tag_regexes(
     }
 
 
+# Type
+Questions = Iterable[MutableMapping[str, Any]]  # TODO: remove this in v5
+
+
 def __getattr__(name: str) -> Any:
     # PEP-562: deprecate module-level variable
 
@@ -176,6 +177,7 @@ def __getattr__(name: str) -> Any:
         "change_type_order": (CHANGE_TYPE_ORDER, "CHANGE_TYPE_ORDER"),
         "encoding": (ENCODING, "ENCODING"),
         "name": (DEFAULT_SETTINGS["name"], "DEFAULT_SETTINGS['name']"),
+        "Questions": (Questions, "Iterable[CzQuestion]"),
     }
     if name in deprecated_vars:
         value, replacement = deprecated_vars[name]

@@ -63,6 +63,7 @@ Before installing Commitizen, ensure you have:
 #### Global Installation (Recommended)
 
 The recommended way to install Commitizen is using [`pipx`](https://pipx.pypa.io/) or [`uv`](https://docs.astral.sh/uv/), which ensures a clean, isolated installation:
+
 **Using pipx:**
 ```bash
 # Install Commitizen
@@ -111,7 +112,7 @@ poetry add commitizen --dev
 
 **Using uv:**
 ```bash
-uv add commitizen
+uv add --dev commitizen
 ```
 
 **Using pdm:**

@@ -31,7 +31,7 @@ cz bump --version-scheme semver
 ```
 
 2. Configuration file:
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_scheme = "semver"
 ```
@@ -113,7 +113,7 @@ Note that as per [semantic versioning spec](https://semver.org/#spec-item-9)
 For example, the following versions (using the [PEP 440](https://peps.python.org/pep-0440/) scheme) are ordered
 by their precedence and showcase how a release might flow through a development cycle:
 
-- `1.0.0` is the current published version
+- `1.0.0` is the currently published version
 - `1.0.1a0` after committing a `fix:` for pre-release
 - `1.1.0a1` after committing an additional `feat:` for pre-release
 - `1.1.0b0` after bumping a beta release
@@ -153,7 +153,7 @@ cz bump --check-consistency
 
 For example, if we have `pyproject.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version = "1.21.0"
 version_files = [
@@ -162,15 +162,16 @@ version_files = [
 ]
 ```
 
-`src/__version__.py`,
+`src/__version__.py`
 
-```python
+
+```python title="src/__version__.py"
 __version__ = "1.21.0"
 ```
 
-and `setup.py`.
+and `setup.py`
 
-```python
+```python title="setup.py"
 from setuptools import setup
 
 setup(..., version="1.0.5", ...)
@@ -193,7 +194,7 @@ cz bump --local-version
 
 For example, if we have `pyproject.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version = "5.3.5+0.1.0"
 ```
@@ -454,7 +455,7 @@ In your `pyproject.toml` or `.cz.toml`
 tag_format = "v$major.$minor.$patch$prerelease"
 ```
 
-The variables must be preceded by a `$` sign and optionally can be wrapped in `{}` . Default is `$version`.
+The variables must be preceded by a `$` sign and optionally can be wrapped in `{}`. The default is `$version`.
 
 Supported variables:
 
@@ -471,7 +472,7 @@ Supported variables:
 
 ### `version_files` \*
 
-It is used to identify the files which should be updated with the new version.
+It is used to identify the files or glob patterns which should be updated with the new version.
 It is also possible to provide a pattern for each file, separated by colons (`:`).
 
 Commitizen will update its configuration file automatically (`pyproject.toml`, `.cz`) when bumping,
@@ -483,11 +484,12 @@ Some examples
 
 `pyproject.toml`, `.cz.toml` or `cz.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_files = [
     "src/__version__.py",
-    "setup.py:version"
+    "packages/*/pyproject.toml:version",
+    "setup.py:version",
 ]
 ```
 
@@ -496,8 +498,7 @@ This means that it will find a file `setup.py` and will only make a change
 in a line containing the `version` substring.
 
 !!! note
-    Files can be specified using relative (to the execution) paths, absolute paths
-    or glob patterns.
+    Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
 
 ---
 
@@ -516,7 +517,7 @@ Some examples
 
 `pyproject.toml`, `.cz.toml` or `cz.toml`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 bump_message = "release $current_version → $new_version [skip-ci]"
 ```
@@ -529,7 +530,7 @@ When set to `true` the changelog is always updated incrementally when running `c
 
 Defaults to: `false`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 update_changelog_on_bump = true
 ```
@@ -540,7 +541,7 @@ update_changelog_on_bump = true
 
 When set to `true`, Commitizen will create annotated tags.
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 annotated_tag = true
 ```
@@ -551,7 +552,7 @@ annotated_tag = true
 
 When set to `true`, Commitizen will create gpg signed tags.
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 gpg_sign = true
 ```
@@ -565,7 +566,7 @@ Useful during the initial development stage of your project.
 
 Defaults to: `false`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 major_version_zero = true
 ```
@@ -591,7 +592,7 @@ execution of the script, some environment variables are available:
 | `CZ_PRE_INCREMENT`           | Whether this is a `MAJOR`, `MINOR` or `PATH` release       |
 | `CZ_PRE_CHANGELOG_FILE_NAME` | Path to the changelog file, if available                   |
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 pre_bump_hooks = [
   "scripts/generate_documentation.sh"
@@ -618,7 +619,7 @@ release. During execution of the script, some environment variables are availabl
 | `CZ_POST_INCREMENT`            | Whether this was a `MAJOR`, `MINOR` or `PATH` release      |
 | `CZ_POST_CHANGELOG_FILE_NAME`  | Path to the changelog file, if available                    |
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 post_bump_hooks = [
   "scripts/slack_notification.sh"
@@ -631,7 +632,7 @@ Offset with which to start counting prereleases.
 
 Defaults to: `0`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 prerelease_offset = 1
 ```
@@ -651,7 +652,7 @@ Options: `pep440`, `semver`, `semver2`
 
 Defaults to: `pep440`
 
-```toml
+```toml title="pyproject.toml"
 [tool.commitizen]
 version_scheme = "semver"
 ```

@@ -24,7 +24,7 @@ Type: `list`
 
 Default: `[ ]`
 
-Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files]
+Files (or glob patterns) where the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files]
 
 ### `version_provider`