DOC/ENH: Clarify usage or configuration files and log about it (#2552)

README.rst

@@ -117,6 +117,17 @@ These are both equivalent to running::
 
     codespell --quiet-level 3 --count --skip "*.po,*.ts,./src/3rdParty,./src/Test"
 
+If several config files are present, they are read in the following order:
+
+#. ``pyproject.toml`` (only if the ``tomli`` library is available)
+#. ``setup.cfg``
+#. ``.codespellrc``
+#. any additional file supplied via ``--config``
+
+If a codespell configuration is supplied in several of these files,
+the configuration from the most recently read file overwrites previously
+specified configurations.
+
 Any options specified in the command line will *override* options from the
 config files.
 

codespell_lib/_codespell.py

@@ -419,8 +419,17 @@ def parse_options(args):
         with open(toml_file, 'rb') as f:
             data = tomli.load(f).get('tool', {})
         config.read_dict(data)
-    config.read(cfg_files)
 
+    # Collect which config files are going to be used
+    used_cfg_files = []
+    for cfg_file in cfg_files:
+        _cfg = configparser.ConfigParser()
+        _cfg.read(cfg_file)
+        if _cfg.has_section('codespell'):
+            used_cfg_files.append(cfg_file)
+
+    # Use config files
+    config.read(cfg_files)
     if config.has_section('codespell'):
         # Build a "fake" argv list using option name and value.
         cfg_args = []
@@ -441,7 +450,7 @@ def parse_options(args):
     if not options.files:
         options.files.append('.')
 
-    return options, parser
+    return options, parser, used_cfg_files
 
 
 def parse_ignore_words_option(ignore_words_option):
@@ -770,7 +779,13 @@ def _script_main():
 
 def main(*args):
     """Contains flow control"""
-    options, parser = parse_options(args)
+    options, parser, used_cfg_files = parse_options(args)
+
+    # Report used config files
+    if len(used_cfg_files) > 0:
+        print('Used config files:')
+    for ifile, cfg_file in enumerate(used_cfg_files, start=1):
+        print('    %i: %s' % (ifile, cfg_file))
 
     if options.regex and options.write_changes:
         print("ERROR: --write-changes cannot be used together with "