feat(bump): add commit filter pattern

[schlotter]

Description

This change adds support for filtering commits before Commitizen evaluates them for version bumps by introducing a new bump_commit_filter_pattern setting.

The new setting defaults to .*, so existing projects keep the current behavior. When configured, cz bump and cz version --next USE_GIT_COMMITS only consider commits whose full message matches the filter pattern before applying the existing bump rules. This is particularly useful for monorepos where only a subset of commits should affect a package's version.

The pull request also updates the related documentation and adds regression tests covering the new filtering behavior and fallback paths.

Checklist

• I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

• Yes (GitHub Copilot CLI)

Generated-by: GitHub Copilot CLI following the guidelines

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained
  • Document any manual testing steps performed
• Update the documentation for the changes

Documentation Changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly
• Check and fix any broken links (internal or external) — There were no broken links.

Expected Behavior

项目 can opt into filtering commits used for bump calculation without changing the default behavior for existing users. With bump_commit_filter_pattern configured, unrelated commits are ignored before bump_pattern is applied, so cz bump and cz version --next USE_GIT_COMMITS derive the next version only from relevant commits.

Steps to Test This Pull Request

1. Configure Commitizen with bump_commit_filter_pattern for a subset of commit messages, for example ^fix\(library-b\):.
2. Create a baseline tag and add commits that include both matching and non-matching messages.
3. Run cz bump --dry-run or cz bump --get-next and confirm that only matching commits affect the calculated increment.
4. Run cz version --project --next USE_GIT_COMMITS and confirm it reports the version derived from the filtered commit set.
5. Remove the setting or leave it at the default and confirm the previous behavior is preserved.

Additional Context

Related discussion: #2075

Manual testing and validation performed during development included targeted pytest coverage for:

• commit filtering in bump calculation
• USE_GIT_COMMITS next-version calculation with filters
• fallback behavior when no explicit filter is configured
• configuration and documentation updates for the new setting

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.31%. Comparing base (d914b4d) to head (1e56d63).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2078      +/-   ##
==========================================
+ Coverage   98.19%   98.31%   +0.11%     
==========================================
  Files          61       61              
  Lines        2829     2851      +22     
==========================================
+ Hits         2778     2803      +25     
+ Misses         51       48       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[woile]

How is this any different from bump_pattern?

[schlotter]

To illustrate the use case, consider the example commit sequence from #2075. In this monorepo, commits related to applications AppA and/or AppB are identified through a custom Applications: line in the commit message:

-- Commit 1 -----
feat: implement library

Applications: ['AppA', 'AppB']

-- Commit 2 -----
fix: fix nasty bug

Applications: ['AppB']

-- Commit 3 -----
ci: change release pipeline

Applications: ['AppA', 'AppB']

-- Commit 4 -----
...

When calculating the version bump for AppA, only commits that affect AppA should be considered. In this example, bump_commit_filter_pattern could be configured as:

(?s)^.*Applications:.*'AppA'.*\].*

This pattern selects only commits that relate to AppA.

bump_pattern cannot be used for this purpose because it is evaluated line by line, rather than against the full commit message.

As implemented today in find_increment() in commitizen/bump.py:

for commit in commits:
    for message in commit.message.split("\n"):
        result = select_pattern.search(message)

(where select_pattern is bump_pattern)

By contrast, bump_commit_filter_pattern would act as a pre-filter on the list of commits considered for version bump calculation and would evaluate the entire commit message. In my PR, this is implemented in filter_commits() in commitizen/bump.py:

return [commit for commit in commits if select_pattern.match(commit.message)]

(where select_pattern is bump_commit_filter_pattern)

I do not think bump_pattern itself can be changed to evaluate the full commit message without introducing a backward compatibility break.

Today, Commitizen evaluates each line of a commit message against bump_pattern, determines whether that line implies a PATCH, MINOR, MAJOR, or no bump, and then uses the highest bump level found within the commit. Existing configurations may rely on this behavior, including the ability to map different lines of the same commit message to different bump levels via bump_map.

For that reason, I see bump_commit_filter_pattern as complementary to bump_pattern rather than a replacement: it decides whether a commit should participate in bump calculation at all, while bump_pattern continues to decide which bump level a selected commit contributes.

[woile]

Yes, but it's the same, now we evaluate twice the commit message.

Why not a setting like split_commit_message?

for commit in commits:
    messages = commit.message.split("\n") if split_commit_message else [commit.message]
    for message in messages:
        result = select_pattern.search(message)

[schlotter]

Mmh, I would still like to support commit messages such as the following:

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Applications: ['AppA', 'AppB']

When calculating the version bump for AppA, I would first want to identify this commit as relevant using a bump_commit_filter_pattern such as:

(?s)^.*Applications:.*'AppA'.*\].*

The commit would then participate in the bump calculation. After that, I would still want the existing bump_pattern / bump_map logic to analyze the commit line by line in order to determine the bump level. In this example, both feat and BREAKING CHANGE would be evaluated, and the resulting bump level would be the highest one found.

This is why I currently do not see how a setting such as split_commit_message would solve the problem. These are actually two separate concerns:

1. Commit filtering: Decide whether a commit is relevant for a particular application. This requires evaluating the entire commit message.
2. Bump calculation: Determine the bump level (PATCH, MINOR, MAJOR) for a relevant commit. This currently relies on evaluating the commit line by line.

In my use case, both behaviors are needed at the same time.

The proposed bump_commit_filter_pattern is intended to address only the first concern. It acts as a pre-filter that decides whether a commit should be considered at all during bump calculation. Once a commit has been selected, the existing bump_pattern behavior can remain unchanged.

This would also be analogous to changelog_pattern, which is used to select commits for changelog generation based on the full commit message. In #2075 I considered reusing changelog_pattern for this purpose, but currently I prefer a dedicated configuration option because changelog generation and bump calculation are conceptually separate features.

[Manny7717]

Verified locally on head 1e56d63. The feature is correctly scoped and the precedence chain is right: cz class attribute (None for custom cz classes, .* default for conventional/customize) -> top-level bump_commit_filter_pattern config -> DEFAULT_SETTINGS fallback, applied consistently in both bump and version commands.

What I re-ran:

• filter_commits edge cases: default .* keeps all commits (backward compatible), anchored re.match at message start, alternation patterns, and a pattern matching zero commits -> empty list.
• Empty filtered list feeds find_increment -> returns None, and the new integration test test_bump_commit_filter_pattern_excludes_all_commits confirms the user-facing NoneIncrementExit ("The commits found are not eligible to be bumped") rather than a crash.
• Customize提交Cz attr wiring: customize.bump_commit_filter_pattern overrides via the existing setattr loop; plain class default otherwise. Consistent with bump_pattern handling.
• Targeted suites (test_bump_command, test_version_command, test_bump_find_increment, test_conf, test_cz_customize): 345 passed. Full suite: only failure is test_bump_pre_commit_changelog[True-pre-commit], which fails identically on base 4184174 (changelog markdown-escaping env difference) — zero new failures.
• ruff + mypy clean.

Docs (bump.md, configuration_file.md, monorepo_guidance.md) explain the feature and its interaction with bump_pattern. No issues found.