feat(config): add warning for multiple configuration files and update documentation #1773

nicoleman0 · 2026-01-05T19:05:52Z

Description

This PR implements a warning system that detects when multiple configuration files exist in the project directory (excluding pyproject.toml) and displays a warning message identifying which file is being used.

The implementation follows the consensus from issue #1702 where maintainers agreed that "we should have one and only one configuration file" and decided to add a warning when multiple config files are detected.

Checklist

I have read the contributing 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) in the documentation

Expected Behavior

When multiple configuration files are detected (e.g., .cz.toml and .cz.json), commitizen will display a warning message like:

Multiple config files detected: .cz.toml, .cz.json. Using config file: '.cz.toml'.

The warning only appears when multiple config files exist (excluding pyproject.toml)
The warning lists all detected config files in the order they would be checked
The warning clearly indicates which file will be used (the first one in the priority order)
If a config file is explicitly specified via the --config flag, no warning is displayed
If only one config file exists (or only pyproject.toml plus one other), no warning is displayed
The file priority order follows the standard commitizen config file precedence.

Fixes #1771

codecov · 2026-01-05T19:07:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.93%. Comparing base (63c529d) to head (9afa4f9).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1773      +/-   ##
==========================================
+ Coverage   97.88%   97.93%   +0.04%     
==========================================
  Files          60       60              
  Lines        2606     2611       +5     
==========================================
+ Hits         2551     2557       +6     
+ Misses         55       54       -1

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

Detects when multiple configuration files exist (excluding pyproject.toml) and displays a warning message identifying which file is being used. Closes commitizen-tools#1771

woile · 2026-01-05T20:11:25Z

commitizen/config/__init__.py

+        # If more than one config file exists, warn the user
+        if len(existing_files) > 1:
+            # Find which one will be used (first non-empty one in the priority order)
+            used_config = None


I don't think we should add the extra steps.
It should just warn that multiple files were detected.
And alternatively, because the list is already in the order that cz is going to pick it put, you could just get the file that it's going to be used by getting the first element of existing_files

Ok, yes that makes sense - I've simplified the implementation:

Removed the extra steps that were checking if each config file is empty

Now just warns about multiple files and uses existing_files[0] to show which file will be used

Changes have been pushed. Let me know if you need anything else.

Remove extra steps to check if config files are empty. Just warn about multiple files and show first file from the list.

commitizen/config/__init__.py

Lee-W · 2026-01-06T02:20:24Z

tests/test_conf.py

+            # Verify the correct config is loaded (first in priority order)
+            assert cfg.settings == _settings
+
+    def test_warn_multiple_config_files_with_pyproject(_, tmpdir, capsys):


But technically, it's multiple configs. We probably should handle it better 🤔

bearomorphism

Great but need some refactoring

commitizen/config/__init__.py

bearomorphism · 2026-01-06T10:34:09Z

Could you add the expected behavior in the PR description? Thanks!

commitizen/config/__init__.py

nicoleman0 · 2026-01-06T11:40:41Z

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.

If I missed anything, let me know again.

bearomorphism · 2026-01-06T13:29:30Z

commitizen/config/__init__.py

+    config_candidates = list(_resolve_config_paths(filepath))
+
+    # Check for multiple config files and warn the user
+    if filepath is None:


I am not sure whether if filepath is None: is still needed. We can perform the check for both cases anyway.

ah yes I see how it's redundant, I'll fix that!

bearomorphism · 2026-01-06T13:32:20Z

commitizen/config/__init__.py

+                f"Using config file: '{filenames[0]}'."
+            )
+
+    for filename in config_candidates:


This for loop looks strange... I think we should remove the for loop

using_config_file = config_candidates[0] ...

but that can be another PR

iirc the underlying logic of BaseConfig is a bit confusing

Ok, so should the code just use config_candidates[0] directly with the first file found, whether it's empty or not?

If so, the behavior would change to:

When filepath is provided: Use that file, raise ConfigFileIsEmpty if empty (same as now)

When auto-discovering: Use the first file found, return empty BaseConfig() if it's empty (currently skips empty files)

This would be simpler and align the warning message with actual behavior. The only downside is if someone has an empty .cz.toml and a valid .cz.json, it would now ignore the .cz.json (whereas currently it would use it).

Shall I go ahead with this simplification in this PR, or would you prefer a separate one?

You could just add a TODO to remind the future contributors to address this issue. The main goal for this PR is just to add a warning for multiple configuration.

bearomorphism · 2026-01-06T13:42:54Z

commitizen/config/__init__.py

+        if len(config_candidates_exclude_pyproject) > 1:
+            filenames = [path.name for path in config_candidates_exclude_pyproject]
+            out.warn(
+                f"Multiple config files detected: {', '.join(filenames)}. "


I am not entirely sure if it's good to just list the filenames but not the full path. There might be files with the same file names but different paths.

bearomorphism · 2026-01-06T13:45:31Z

commitizen/config/__init__.py

+            filenames = [path.name for path in config_candidates_exclude_pyproject]
+            out.warn(
+                f"Multiple config files detected: {', '.join(filenames)}. "
+                f"Using config file: '{filenames[0]}'."


I am not sure if the used config file here will be the same as the returned config file around the line if not conf.is_empty_config:.

In other words, will the return value of this function always be config_candidates[0]?

@Lee-W @woile @noirbizarre wdyt

bearomorphism · 2026-01-06T13:48:53Z

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.

If I missed anything, let me know again.

@nicoleman0 you're doing it great! But the pipeline is failing because some of the commit messages does not follow the requirements. Could you fix the commit messages? Thanks!

Co-authored-by: Wei Lee <[email protected]>

Co-authored-by: Tim Hsiung <[email protected]>

…efactor read_cfg function

nicoleman0 · 2026-01-06T14:09:52Z

Could you add the expected behavior in the PR description? Thanks!

I just updated the PR with the expected behavior (sorry about that, completely forgot to add that part), and also refactored my code with the suggestions that you all gave.
If I missed anything, let me know again.

@nicoleman0 you're doing it great! But the pipeline is failing because some of the commit messages does not follow the requirements. Could you fix the commit messages? Thanks!

@bearomorphism I believe I've fixed the generic commit messages and I also refactored the read_cfg function.

The redundant if filepath is None: check has been removed. The code now performs the multiple config file check in both cases, though it will only ever warn when filepath is None.

nicoleman0 requested review from Lee-W, noirbizarre and woile as code owners January 5, 2026 19:05

github-actions bot added pr-status: wait-for-review type: documentation type: feature A new enhacement proposal labels Jan 5, 2026

feat(config): add warning for multiple configuration files

c03d500

Detects when multiple configuration files exist (excluding pyproject.toml) and displays a warning message identifying which file is being used. Closes commitizen-tools#1771

nicoleman0 force-pushed the fix-config-warning branch from 2489068 to c03d500 Compare January 5, 2026 19:10

Merge branch 'master' into fix-config-warning

ad49e81

woile reviewed Jan 5, 2026

View reviewed changes

refactor: simplify multiple config files warning

87bf26f

Remove extra steps to check if config files are empty. Just warn about multiple files and show first file from the list.

Lee-W reviewed Jan 6, 2026

View reviewed changes

bearomorphism requested changes Jan 6, 2026

View reviewed changes

commitizen/config/__init__.py Outdated Show resolved Hide resolved

commitizen/config/__init__.py Outdated Show resolved Hide resolved

commitizen/config/__init__.py Outdated Show resolved Hide resolved

bearomorphism added pr-status: wait-for-modification and removed pr-status: wait-for-review labels Jan 6, 2026

bearomorphism reviewed Jan 6, 2026

View reviewed changes

commitizen/config/__init__.py Outdated Show resolved Hide resolved

bearomorphism reviewed Jan 6, 2026

View reviewed changes

commitizen/config/__init__.py Outdated Show resolved Hide resolved

github-actions bot added the pr-status: wait-for-review label Jan 6, 2026

bearomorphism reviewed Jan 6, 2026

View reviewed changes

nicoleman0 and others added 5 commits January 6, 2026 14:00

refactor(config): use walrus operator for git_project_root assignment

f825cd9

Co-authored-by: Wei Lee <[email protected]>

fix(config): only check for multiple configs when filepath is None

77c2cdf

Co-authored-by: Tim Hsiung <[email protected]>

fix(config): improve warning message clarity for multiple config files

6b8aef4

Co-authored-by: Tim Hsiung <[email protected]>

refactor(config): remove _check_and_warn_multiple_configs function; r…

f2c8e4f

…efactor read_cfg function

fix(config): streamline multiple config files warning logic

f0fc425

nicoleman0 force-pushed the fix-config-warning branch from d3154d4 to f0fc425 Compare January 6, 2026 14:04

Merge branch 'master' into fix-config-warning

e900199

Merge branch 'master' into fix-config-warning

9afa4f9

Uh oh!

feat(config): add warning for multiple configuration files and update documentation #1773

Are you sure you want to change the base?

feat(config): add warning for multiple configuration files and update documentation #1773

Uh oh!

Conversation

nicoleman0 commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Code Changes

Documentation Changes

Expected Behavior

Uh oh!

codecov bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicoleman0 Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bearomorphism left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bearomorphism commented Jan 6, 2026

Uh oh!

Uh oh!

Uh oh!

nicoleman0 commented Jan 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicoleman0 Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bearomorphism commented Jan 6, 2026

Uh oh!

nicoleman0 commented Jan 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nicoleman0 commented Jan 5, 2026 •

edited

Loading

codecov bot commented Jan 5, 2026 •

edited

Loading

nicoleman0 Jan 5, 2026 •

edited

Loading

nicoleman0 Jan 6, 2026 •

edited

Loading