Skip to content

Commit 10657a7

Browse files
commitizenbot[bot]commitizenbot[bot]
committed
Deploying to gh-pages from @ 3f5ccc8 🚀
1 parent eff7c44 commit 10657a7

11 files changed

Lines changed: 350 additions & 51 deletions

File tree

‎customization/python_class/index.html‎

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1038,6 +1038,17 @@
10381038
<nav class="md-nav" aria-label="Custom bump rules">
10391039
<ul class="md-nav__list">
10401040

1041+
<li class="md-nav__item">
1042+
<a href="#filter-commits-before-bump-and-changelog-generation" class="md-nav__link">
1043+
<span class="md-ellipsis">
1044+
1045+
Filter commits before bump and changelog generation
1046+
1047+
</span>
1048+
</a>
1049+
1050+
</li>
1051+
10411052
<li class="md-nav__item">
10421053
<a href="#custom-commit-validation-and-error-message" class="md-nav__link">
10431054
<span class="md-ellipsis">
@@ -2138,6 +2149,17 @@
21382149
<nav class="md-nav" aria-label="Custom bump rules">
21392150
<ul class="md-nav__list">
21402151

2152+
<li class="md-nav__item">
2153+
<a href="#filter-commits-before-bump-and-changelog-generation" class="md-nav__link">
2154+
<span class="md-ellipsis">
2155+
2156+
Filter commits before bump and changelog generation
2157+
2158+
</span>
2159+
</a>
2160+
2161+
</li>
2162+
21412163
<li class="md-nav__item">
21422164
<a href="#custom-commit-validation-and-error-message" class="md-nav__link">
21432165
<span class="md-ellipsis">
@@ -2336,6 +2358,103 @@ <h2 id="custom-bump-rules">Custom bump rules<a class="headerlink" href="#custom-
23362358
<p>That's it, your Commitizen now supports custom rules, and you can run.</p>
23372359
<div class="highlight"><pre><span></span><code>cz<span class="w"> </span>-n<span class="w"> </span>cz_strange<span class="w"> </span>bump
23382360
</code></pre></div>
2361+
<h3 id="filter-commits-before-bump-and-changelog-generation">Filter commits before bump and changelog generation<a class="headerlink" href="#filter-commits-before-bump-and-changelog-generation" title="Permanent link">&para;</a></h3>
2362+
<p>Custom rules can select which commits are relevant before Commitizen calculates a
2363+
version increment or generates a changelog.</p>
2364+
<table>
2365+
<thead>
2366+
<tr>
2367+
<th>Method</th>
2368+
<th>Used by</th>
2369+
<th>Default behavior</th>
2370+
</tr>
2371+
</thead>
2372+
<tbody>
2373+
<tr>
2374+
<td><code>filter_commits</code></td>
2375+
<td>Shared by the operation-specific methods</td>
2376+
<td>Return all commits unchanged</td>
2377+
</tr>
2378+
<tr>
2379+
<td><code>filter_commits_before_bump</code></td>
2380+
<td><code>cz bump</code> and <code>cz version --next USE_GIT_COMMITS</code></td>
2381+
<td>Call <code>filter_commits</code></td>
2382+
</tr>
2383+
<tr>
2384+
<td><code>filter_commits_before_changelog</code></td>
2385+
<td><code>cz changelog</code>, including changelogs created by bump</td>
2386+
<td>Call <code>filter_commits</code></td>
2387+
</tr>
2388+
</tbody>
2389+
</table>
2390+
<p>Override <code>filter_commits</code> when bump and changelog generation should use the same
2391+
selection. Override an operation-specific method when their selections should
2392+
differ. These methods do not affect <code>cz check</code>.</p>
2393+
<p>For example, a monorepo can use a full commit-message metadata line to associate
2394+
commits with applications:</p>
2395+
<div class="highlight"><pre><span></span><code>feat: add shared library
2396+
2397+
Applications: [&#39;AppA&#39;, &#39;AppB&#39;]
2398+
</code></pre></div>
2399+
<p>A plugin can retain the built-in Conventional Commits behavior while filtering
2400+
on that metadata:</p>
2401+
<div class="highlight"><span class="filename">cz_applications.py</span><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">re</span>
2402+
2403+
<span class="kn">from</span><span class="w"> </span><span class="nn">commitizen</span><span class="w"> </span><span class="kn">import</span> <span class="n">git</span>
2404+
<span class="kn">from</span><span class="w"> </span><span class="nn">commitizen.cz.conventional_commits</span><span class="w"> </span><span class="kn">import</span> <span class="n">ConventionalCommitsCz</span>
2405+
<span class="kn">from</span><span class="w"> </span><span class="nn">commitizen.exceptions</span><span class="w"> </span><span class="kn">import</span> <span class="n">InvalidConfigurationError</span>
2406+
2407+
2408+
<span class="k">class</span><span class="w"> </span><span class="nc">ApplicationsCommitizen</span><span class="p">(</span><span class="n">ConventionalCommitsCz</span><span class="p">):</span>
2409+
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Apply Conventional Commits rules to one configured application.</span>
2410+
2411+
<span class="sd"> Example:</span>
2412+
<span class="sd"> Configure `app = &quot;AppA&quot;` to keep commits whose `Applications:` metadata</span>
2413+
<span class="sd"> includes `AppA`.</span>
2414+
<span class="sd"> &quot;&quot;&quot;</span>
2415+
2416+
<span class="k">def</span><span class="w"> </span><span class="nf">filter_commits</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">commits</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">git</span><span class="o">.</span><span class="n">GitCommit</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">git</span><span class="o">.</span><span class="n">GitCommit</span><span class="p">]:</span>
2417+
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Keep commits associated with the configured application.</span>
2418+
2419+
<span class="sd"> Args:</span>
2420+
<span class="sd"> commits: The commits available to the current operation.</span>
2421+
2422+
<span class="sd"> Returns:</span>
2423+
<span class="sd"> Commits whose full message lists the configured application.</span>
2424+
2425+
<span class="sd"> Raises:</span>
2426+
<span class="sd"> InvalidConfigurationError: If the plugin&#39;s `app` setting is missing.</span>
2427+
<span class="sd"> &quot;&quot;&quot;</span>
2428+
<span class="n">application</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">settings</span><span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;app&quot;</span><span class="p">)</span>
2429+
<span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">application</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">application</span><span class="p">:</span>
2430+
<span class="k">raise</span> <span class="n">InvalidConfigurationError</span><span class="p">(</span>
2431+
<span class="s2">&quot;cz_applications requires a non-empty &#39;app&#39; setting&quot;</span>
2432+
<span class="p">)</span>
2433+
2434+
<span class="n">application_line</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span>
2435+
<span class="sa">rf</span><span class="s2">&quot;&quot;&quot;^Applications:\s*\[[^\]]*[&#39;&quot;]</span><span class="si">{</span><span class="n">re</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">application</span><span class="p">)</span><span class="si">}</span><span class="s2">[&#39;&quot;][^\]]*\]\s*$&quot;&quot;&quot;</span><span class="p">,</span>
2436+
<span class="n">re</span><span class="o">.</span><span class="n">MULTILINE</span><span class="p">,</span>
2437+
<span class="p">)</span>
2438+
<span class="k">return</span> <span class="p">[</span><span class="n">commit</span> <span class="k">for</span> <span class="n">commit</span> <span class="ow">in</span> <span class="n">commits</span> <span class="k">if</span> <span class="n">application_line</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">commit</span><span class="o">.</span><span class="n">message</span><span class="p">)]</span>
2439+
</code></pre></div>
2440+
<p>Expose the class through the plugin package:</p>
2441+
<div class="highlight"><span class="filename">pyproject.toml</span><pre><span></span><code><span class="k">[project.entry-points.</span><span class="s2">&quot;commitizen.plugin&quot;</span><span class="k">]</span>
2442+
<span class="n">cz_applications</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;cz_applications:ApplicationsCommitizen&quot;</span>
2443+
</code></pre></div>
2444+
<p>Then select the plugin and application in each component's configuration:</p>
2445+
<div class="highlight"><span class="filename">app-a/.cz.toml</span><pre><span></span><code><span class="k">[tool.commitizen]</span>
2446+
<span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;cz_applications&quot;</span>
2447+
<span class="n">app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;AppA&quot;</span>
2448+
<span class="n">version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;1.0.0&quot;</span>
2449+
<span class="n">tag_format</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;$version-app-a&quot;</span>
2450+
</code></pre></div>
2451+
<p><code>app</code> is owned and interpreted by this plugin; it is not a built-in Commitizen
2452+
setting. TOML keys under <code>[tool.commitizen]</code> are available through
2453+
<code>self.config.settings</code>. The declarative <code>[tool.commitizen.customize]</code> section
2454+
cannot override Python methods, so this use case requires a Python plugin.</p>
2455+
<p>Filtering happens before the existing rule processing. The retained commits are
2456+
still interpreted by <code>bump_pattern</code> and <code>bump_map</code> for version increments and by
2457+
<code>changelog_pattern</code> and <code>commit_parser</code> for changelog entries.</p>
23392458
<h3 id="custom-commit-validation-and-error-message">Custom commit validation and error message<a class="headerlink" href="#custom-commit-validation-and-error-message" title="Permanent link">&para;</a></h3>
23402459
<p>The commit message validation can be customized by overriding the <code>validate_commit_message</code> and <code>format_error_message</code>
23412460
methods from <code>BaseCommitizen</code>. This allows for a more detailed feedback to the user where the error originates from.</p>
@@ -2559,7 +2678,7 @@ <h3 id="example">Example<a class="headerlink" href="#example" title="Permanent l
25592678
<span class="md-icon" title="Last update">
25602679
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
25612680
</span>
2562-
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="November 19, 2025 09:12:08 UTC">November 19, 2025</span>
2681+
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="September 17, 2026 19:44:31 UTC">September 17, 2026</span>
25632682
</span>
25642683

25652684

‎customization/python_class/index.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,96 @@ That's it, your Commitizen now supports custom rules, and you can run.
125125
cz -n cz_strange bump
126126
```
127127

128+
### Filter commits before bump and changelog generation
129+
130+
Custom rules can select which commits are relevant before Commitizen calculates a version increment or generates a changelog.
131+
132+
| Method | Used by | Default behavior |
133+
| --------------------------------- | ---------------------------------------------------- | ---------------------------- |
134+
| `filter_commits` | Shared by the operation-specific methods | Return all commits unchanged |
135+
| `filter_commits_before_bump` | `cz bump` and `cz version --next USE_GIT_COMMITS` | Call `filter_commits` |
136+
| `filter_commits_before_changelog` | `cz changelog`, including changelogs created by bump | Call `filter_commits` |
137+
138+
Override `filter_commits` when bump and changelog generation should use the same selection. Override an operation-specific method when their selections should differ. These methods do not affect `cz check`.
139+
140+
For example, a monorepo can use a full commit-message metadata line to associate commits with applications:
141+
142+
```
143+
feat: add shared library
144+
145+
Applications: ['AppA', 'AppB']
146+
```
147+
148+
A plugin can retain the built-in Conventional Commits behavior while filtering on that metadata:
149+
150+
cz_applications.py
151+
152+
```
153+
import re
154+
155+
from commitizen import git
156+
from commitizen.cz.conventional_commits import ConventionalCommitsCz
157+
from commitizen.exceptions import InvalidConfigurationError
158+
159+
160+
class ApplicationsCommitizen(ConventionalCommitsCz):
161+
"""Apply Conventional Commits rules to one configured application.
162+
163+
Example:
164+
Configure `app = "AppA"` to keep commits whose `Applications:` metadata
165+
includes `AppA`.
166+
"""
167+
168+
def filter_commits(self, commits: list[git.GitCommit]) -> list[git.GitCommit]:
169+
"""Keep commits associated with the configured application.
170+
171+
Args:
172+
commits: The commits available to the current operation.
173+
174+
Returns:
175+
Commits whose full message lists the configured application.
176+
177+
Raises:
178+
InvalidConfigurationError: If the plugin's `app` setting is missing.
179+
"""
180+
application = dict(self.config.settings).get("app")
181+
if not isinstance(application, str) or not application:
182+
raise InvalidConfigurationError(
183+
"cz_applications requires a non-empty 'app' setting"
184+
)
185+
186+
application_line = re.compile(
187+
rf"""^Applications:\s*\[[^\]]*['"]{re.escape(application)}['"][^\]]*\]\s*$""",
188+
re.MULTILINE,
189+
)
190+
return [commit for commit in commits if application_line.search(commit.message)]
191+
```
192+
193+
Expose the class through the plugin package:
194+
195+
pyproject.toml
196+
197+
```
198+
[project.entry-points."commitizen.plugin"]
199+
cz_applications = "cz_applications:ApplicationsCommitizen"
200+
```
201+
202+
Then select the plugin and application in each component's configuration:
203+
204+
app-a/.cz.toml
205+
206+
```
207+
[tool.commitizen]
208+
name = "cz_applications"
209+
app = "AppA"
210+
version = "1.0.0"
211+
tag_format = "$version-app-a"
212+
```
213+
214+
`app` is owned and interpreted by this plugin; it is not a built-in Commitizen setting. TOML keys under `[tool.commitizen]` are available through `self.config.settings`. The declarative `[tool.commitizen.customize]` section cannot override Python methods, so this use case requires a Python plugin.
215+
216+
Filtering happens before the existing rule processing. The retained commits are still interpreted by `bump_pattern` and `bump_map` for version increments and by `changelog_pattern` and `commit_parser` for changelog entries.
217+
128218
### Custom commit validation and error message
129219

130220
The commit message validation can be customized by overriding the `validate_commit_message` and `format_error_message` methods from `BaseCommitizen`. This allows for a more detailed feedback to the user where the error originates from.

‎images/cli_interactive/bump.gif‎

617 Bytes
Loading

‎images/cli_interactive/commit.gif‎

-227 Bytes
Loading

‎images/cli_interactive/init.gif‎

-1.75 KB
Loading

‎images/cli_interactive/shortcut_custom.gif‎

-74 Bytes
Loading

‎images/cli_interactive/shortcut_default.gif‎

-1.3 KB
Loading

‎llms-full.txt‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3018,6 +3018,96 @@ That's it, your Commitizen now supports custom rules, and you can run.
30183018
cz -n cz_strange bump
30193019
```
30203020

3021+
### Filter commits before bump and changelog generation
3022+
3023+
Custom rules can select which commits are relevant before Commitizen calculates a version increment or generates a changelog.
3024+
3025+
| Method | Used by | Default behavior |
3026+
| --------------------------------- | ---------------------------------------------------- | ---------------------------- |
3027+
| `filter_commits` | Shared by the operation-specific methods | Return all commits unchanged |
3028+
| `filter_commits_before_bump` | `cz bump` and `cz version --next USE_GIT_COMMITS` | Call `filter_commits` |
3029+
| `filter_commits_before_changelog` | `cz changelog`, including changelogs created by bump | Call `filter_commits` |
3030+
3031+
Override `filter_commits` when bump and changelog generation should use the same selection. Override an operation-specific method when their selections should differ. These methods do not affect `cz check`.
3032+
3033+
For example, a monorepo can use a full commit-message metadata line to associate commits with applications:
3034+
3035+
```
3036+
feat: add shared library
3037+
3038+
Applications: ['AppA', 'AppB']
3039+
```
3040+
3041+
A plugin can retain the built-in Conventional Commits behavior while filtering on that metadata:
3042+
3043+
cz_applications.py
3044+
3045+
```
3046+
import re
3047+
3048+
from commitizen import git
3049+
from commitizen.cz.conventional_commits import ConventionalCommitsCz
3050+
from commitizen.exceptions import InvalidConfigurationError
3051+
3052+
3053+
class ApplicationsCommitizen(ConventionalCommitsCz):
3054+
"""Apply Conventional Commits rules to one configured application.
3055+
3056+
Example:
3057+
Configure `app = "AppA"` to keep commits whose `Applications:` metadata
3058+
includes `AppA`.
3059+
"""
3060+
3061+
def filter_commits(self, commits: list[git.GitCommit]) -> list[git.GitCommit]:
3062+
"""Keep commits associated with the configured application.
3063+
3064+
Args:
3065+
commits: The commits available to the current operation.
3066+
3067+
Returns:
3068+
Commits whose full message lists the configured application.
3069+
3070+
Raises:
3071+
InvalidConfigurationError: If the plugin's `app` setting is missing.
3072+
"""
3073+
application = dict(self.config.settings).get("app")
3074+
if not isinstance(application, str) or not application:
3075+
raise InvalidConfigurationError(
3076+
"cz_applications requires a non-empty 'app' setting"
3077+
)
3078+
3079+
application_line = re.compile(
3080+
rf"""^Applications:\s*\[[^\]]*['"]{re.escape(application)}['"][^\]]*\]\s*$""",
3081+
re.MULTILINE,
3082+
)
3083+
return [commit for commit in commits if application_line.search(commit.message)]
3084+
```
3085+
3086+
Expose the class through the plugin package:
3087+
3088+
pyproject.toml
3089+
3090+
```
3091+
[project.entry-points."commitizen.plugin"]
3092+
cz_applications = "cz_applications:ApplicationsCommitizen"
3093+
```
3094+
3095+
Then select the plugin and application in each component's configuration:
3096+
3097+
app-a/.cz.toml
3098+
3099+
```
3100+
[tool.commitizen]
3101+
name = "cz_applications"
3102+
app = "AppA"
3103+
version = "1.0.0"
3104+
tag_format = "$version-app-a"
3105+
```
3106+
3107+
`app` is owned and interpreted by this plugin; it is not a built-in Commitizen setting. TOML keys under `[tool.commitizen]` are available through `self.config.settings`. The declarative `[tool.commitizen.customize]` section cannot override Python methods, so this use case requires a Python plugin.
3108+
3109+
Filtering happens before the existing rule processing. The retained commits are still interpreted by `bump_pattern` and `bump_map` for version increments and by `changelog_pattern` and `commit_parser` for changelog entries.
3110+
30213111
### Custom commit validation and error message
30223112

30233113
The commit message validation can be customized by overriding the `validate_commit_message` and `format_error_message` methods from `BaseCommitizen`. This allows for a more detailed feedback to the user where the error originates from.

‎search/search_index.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)