feat(config): add warning for multiple configuration files

Detects when multiple configuration files exist (excluding pyproject.toml)
and displays a warning message identifying which file is being used.

Closes #1771

Author: nicoleman0

commitizen/config/__init__.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from commitizen import defaults, git
+from commitizen import defaults, git, out
 from commitizen.config.factory import create_config
 from commitizen.exceptions import ConfigFileIsEmpty, ConfigFileNotFound
 
@@ -34,7 +34,53 @@ def _resolve_config_paths(filepath: str | None = None) -> Generator[Path, None,
                 yield out_path
 
 
+def _check_and_warn_multiple_configs(filepath: str | None = None) -> None:
+    """Check if multiple config files exist and warn the user."""
+    if filepath is not None:
+        # If user explicitly specified a config file, no need to warn
+        return
+
+    git_project_root = git.find_git_project_root()
+    cfg_search_paths = [Path(".")]
+    if git_project_root:
+        cfg_search_paths.append(git_project_root)
+
+    for path in cfg_search_paths:
+        # Find all existing config files (excluding pyproject.toml for clearer warning)
+        existing_files = [
+            filename
+            for filename in defaults.CONFIG_FILES
+            if filename != "pyproject.toml" and (path / filename).exists()
+        ]
+
+        # 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
+            for filename in defaults.CONFIG_FILES:
+                config_path = path / filename
+                if config_path.exists():
+                    try:
+                        with open(config_path, "rb") as f:
+                            data = f.read()
+                        conf = create_config(data=data, path=config_path)
+                        if not conf.is_empty_config:
+                            used_config = filename
+                            break
+                    except Exception:
+                        continue
+
+            if used_config:
+                out.warn(
+                    f"Multiple config files detected: {', '.join(existing_files)}. "
+                    f"Using {used_config}."
+                )
+            break
+
+
 def read_cfg(filepath: str | None = None) -> BaseConfig:
+    _check_and_warn_multiple_configs(filepath)
+
     for filename in _resolve_config_paths(filepath):
         with open(filename, "rb") as f:
             data: bytes = f.read()

docs/config/configuration_file.md

@@ -23,6 +23,9 @@ The first valid configuration file found will be used. If no configuration file
 !!! tip
     For Python projects, it's recommended to add your Commitizen configuration to `pyproject.toml` to keep all project configuration in one place.
 
+!!! warning "Multiple Configuration Files"
+    If Commitizen detects more than one configuration file in your project directory (excluding `pyproject.toml`), it will display a warning message and identify which file is being used. To avoid confusion, ensure you have only one Commitizen configuration file in your project.
+
 ## Supported Formats
 
 Commitizen supports three configuration file formats:

tests/test_conf.py

@@ -239,6 +239,90 @@ def test_load_empty_pyproject_toml_from_config_argument(_, tmpdir):
             with pytest.raises(ConfigFileIsEmpty):
                 config.read_cfg(filepath="./not_in_root/pyproject.toml")
 
+    def test_warn_multiple_config_files(_, tmpdir, capsys):
+        """Test that a warning is issued when multiple config files exist."""
+        with tmpdir.as_cwd():
+            # Create multiple config files
+            tmpdir.join(".cz.toml").write(PYPROJECT)
+            tmpdir.join(".cz.json").write(JSON_STR)
+
+            # Read config
+            cfg = config.read_cfg()
+
+            # Check that the warning was issued
+            captured = capsys.readouterr()
+            assert "Multiple config files detected" in captured.err
+            assert ".cz.toml" in captured.err
+            assert ".cz.json" in captured.err
+            assert "Using" in captured.err
+
+            # Verify the correct config is loaded (first in priority order)
+            assert cfg.settings == _settings
+
+    def test_warn_multiple_config_files_with_pyproject(_, tmpdir, capsys):
+        """Test warning excludes pyproject.toml from the warning message."""
+        with tmpdir.as_cwd():
+            # Create multiple config files including pyproject.toml
+            tmpdir.join("pyproject.toml").write(PYPROJECT)
+            tmpdir.join(".cz.json").write(JSON_STR)
+
+            # Read config - should use pyproject.toml (first in priority)
+            cfg = config.read_cfg()
+
+            # No warning should be issued as only one non-pyproject config exists
+            captured = capsys.readouterr()
+            assert "Multiple config files detected" not in captured.err
+
+            # Verify the correct config is loaded
+            assert cfg.settings == _settings
+
+    def test_warn_multiple_config_files_uses_correct_one(_, tmpdir, capsys):
+        """Test that the correct config file is used when multiple exist."""
+        with tmpdir.as_cwd():
+            # Create .cz.json with different settings
+            json_different = """
+            {
+                "commitizen": {
+                    "name": "cz_conventional_commits",
+                    "version": "2.0.0"
+                }
+            }
+            """
+            tmpdir.join(".cz.json").write(json_different)
+            tmpdir.join(".cz.toml").write(PYPROJECT)
+
+            # Read config - should use pyproject.toml (first in defaults.CONFIG_FILES)
+            # But since pyproject.toml doesn't exist, .cz.toml is second in priority
+            cfg = config.read_cfg()
+
+            # Check that warning mentions both files
+            captured = capsys.readouterr()
+            assert "Multiple config files detected" in captured.err
+            assert ".cz.toml" in captured.err
+            assert ".cz.json" in captured.err
+
+            # Verify .cz.toml was used (second in priority after pyproject.toml)
+            assert cfg.settings["name"] == "cz_jira"  # from PYPROJECT
+            assert cfg.settings["version"] == "1.0.0"
+
+    def test_no_warn_with_explicit_config_path(_, tmpdir, capsys):
+        """Test that no warning is issued when user explicitly specifies config."""
+        with tmpdir.as_cwd():
+            # Create multiple config files
+            tmpdir.join(".cz.toml").write(PYPROJECT)
+            tmpdir.join(".cz.json").write(JSON_STR)
+
+            # Read config with explicit path
+            cfg = config.read_cfg(filepath=".cz.json")
+
+            # No warning should be issued
+            captured = capsys.readouterr()
+            assert "Multiple config files detected" not in captured.err
+
+            # Verify the explicitly specified config is loaded (compare to expected JSON config)
+            json_cfg_expected = JsonConfig(data=JSON_STR, path=Path(".cz.json"))
+            assert cfg.settings == json_cfg_expected.settings
+
 
 @pytest.mark.parametrize(
     "config_file, exception_string",