fix: add logging for file inclusion (#1110)

Author: henryiii

docs/about/changelog.md

@@ -9,6 +9,8 @@ Fixes:
 
 - Improve `.gitignore` iteration speed by @silversquirl in #1103
 - Warn on 3.13.4 on Windows by @henryiii in #1104
+- Add debug logging explaining why a file is included/excluded by @henryiii in
+  #1110
 
 Documentation:
 

src/scikit_build_core/build/_file_processor.py

@@ -7,7 +7,8 @@
 
 import pathspec
 
-from scikit_build_core.format import pyproject_format
+from .._logging import logger
+from ..format import pyproject_format
 
 if TYPE_CHECKING:
     from collections.abc import Generator, Sequence
@@ -72,19 +73,31 @@ def each_unignored_file(
         for p in all_paths:
             # Always include something included
             if include_spec.match_file(p):
+                logger.debug("Including {} because it is explicitly included.", p)
                 yield p
                 continue
 
             # Always exclude something excluded
             if user_exclude_spec.match_file(p):
+                logger.debug(
+                    "Excluding {} because it is explicitly excluded by the user.", p
+                )
                 continue
 
             # Ignore from global ignore
             if global_exclude_spec.match_file(p):
+                logger.debug(
+                    "Excluding {} because it is explicitly excluded by the global ignore.",
+                    p,
+                )
                 continue
 
             # Ignore built-in patterns
             if builtin_exclude_spec.match_file(p):
+                logger.debug(
+                    "Excluding {} because it is excluded by the built-in ignore patterns.",
+                    p,
+                )
                 continue
 
             # Check relative ignores (Python 3.9's is_relative_to workaround)
@@ -93,6 +106,10 @@ def each_unignored_file(
                 for np, nex in nested_excludes.items()
                 if dirpath == np or np in dirpath.parents
             ):
+                logger.debug(
+                    "Excluding {} because it is explicitly excluded by nested ignore.",
+                    p,
+                )
                 continue
 
             yield p