fix #1115: explicitly document file finder behaviour

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -20,6 +20,7 @@
 - reintroduce Python 3.9 entrypoints shim for compatibility
 - fix #1136: update customizing.md to fix missing import
 - fix #1001: document the missing version schemes and add examples in the docs
+- fix #1115: explicitly document file finder behaviour
 
 ## v8.3.1
 

README.md

@@ -17,6 +17,8 @@ files that are managed by the SCM
 Unwanted files must be excluded via `MANIFEST.in`
 or [configuring Git archive][git-archive-docs].
 
+> **⚠️ Important:** Installing setuptools-scm automatically enables a file finder that includes **all SCM-tracked files** in your source distributions. This can be surprising if you have development files tracked in Git/Mercurial that you don't want in your package. Use `MANIFEST.in` to exclude unwanted files. See the [documentation] for details.
+
 ## `pyproject.toml` usage
 
 The preferred way to configure [setuptools-scm] is to author

docs/config.md

@@ -152,6 +152,66 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 
 
 
+## automatic file inclusion
+
+!!! warning "Setuptools File Finder Integration"
+
+    `setuptools-scm` automatically registers a setuptools file finder that includes all SCM-tracked files in source distributions. This behavior is **always active** when setuptools-scm is installed, regardless of whether you use it for versioning.
+
+**How it works:**
+
+`setuptools-scm` provides a `setuptools.file_finders` entry point that:
+
+1. Automatically discovers SCM-managed files (Git, Mercurial)
+2. Includes them in source distributions (`python -m build --sdist`)
+3. Works for `include_package_data = True` in package building
+
+**Entry point registration:**
+```toml
+[project.entry-points."setuptools.file_finders"]
+setuptools_scm = "setuptools_scm._file_finders:find_files"
+```
+
+**Files included by default:**
+- All files tracked by Git (`git ls-files`)
+- All files tracked by Mercurial (`hg files`)
+- Includes: source code, documentation, tests, config files, etc.
+- Excludes: untracked files, files in `.gitignore`/`.hgignore`
+
+**Controlling inclusion:**
+
+Use `MANIFEST.in` to override the automatic behavior:
+
+```text title="MANIFEST.in"
+# Exclude development files
+exclude .pre-commit-config.yaml
+exclude tox.ini
+global-exclude *.pyc __pycache__/
+
+# Exclude entire directories
+prune docs/
+prune testing/
+
+# Include non-SCM files
+include data/important.json
+```
+
+**Debugging file inclusion:**
+
+```bash
+# List files that will be included
+python -m setuptools_scm ls
+
+# Build and inspect sdist contents
+python -m build --sdist
+tar -tzf dist/package-*.tar.gz
+```
+
+!!! note "Cannot be disabled"
+
+    The file finder cannot be disabled through configuration - it's automatically active when setuptools-scm is installed. If you need to disable it completely, you must remove setuptools-scm from your build environment (which also means you can't use it for versioning).
+
+
 ## api reference
 
 ### constants

docs/index.md

@@ -10,6 +10,16 @@ files that are managed by the SCM
 Unwanted files must be excluded via `MANIFEST.in`
 or [configuring Git archive][git-archive-docs].
 
+!!! warning "Automatic File Inclusion Behavior"
+
+    **Important:** Simply installing `setuptools-scm` as a build dependency will automatically enable its file finder, which includes **all SCM-tracked files** in your source distributions. This happens even if you're not using setuptools-scm for versioning.
+
+    - ✅ **Expected**: All Git/Mercurial tracked files will be included in your sdist
+    - ⚠️ **Surprise**: This includes development files, configs, tests, docs, etc.
+    - 🛠️ **Control**: Use `MANIFEST.in` to exclude unwanted files
+
+    See the [File Finder Documentation](usage.md#file-finders-hook-makes-most-of-manifestin-unnecessary) for details.
+
 [git-archive-docs]: usage.md#builtin-mechanisms-for-obtaining-version-numbers
 
 ## Basic usage

docs/usage.md

@@ -285,6 +285,12 @@ be kept in version control. It's strongly recommended to be put into gitignore.
 
 ### File finders hook makes most of `MANIFEST.in` unnecessary
 
+!!! warning "Automatic File Inclusion"
+
+    **`setuptools-scm` automatically provides a setuptools file finder by default.** This means that when you install setuptools-scm, it will automatically include **all SCM-tracked files** in your source distributions (sdist) without requiring a `MANIFEST.in` file.
+
+    This automatic behavior can be surprising if you're not expecting it. The file finder is active as soon as setuptools-scm is installed in your build environment.
+
 `setuptools-scm` implements a [file_finders] entry point
 which returns all files tracked by your SCM.
 This eliminates the need for a manually constructed `MANIFEST.in` in most cases where this
@@ -293,6 +299,63 @@ would be required when not using `setuptools-scm`, namely:
 * To ensure all relevant files are packaged when running the `sdist` command.
   * When using [include_package_data] to include package data as part of the `build` or `bdist_wheel`.
 
+#### How it works
+
+The file finder integration works through setuptools' plugin system:
+
+1. **Entry Point Registration**: setuptools-scm registers itself as a file finder via the `setuptools.file_finders` entry point
+2. **Automatic Discovery**: When setuptools builds a source distribution, it automatically calls setuptools-scm to get the list of files
+3. **SCM Integration**: setuptools-scm queries your SCM (Git, Mercurial) to get all tracked files
+4. **File Inclusion**: All SCM-tracked files are automatically included in the sdist
+
+#### Controlling file inclusion
+
+**Using MANIFEST.in**: You can still use `MANIFEST.in` to override the automatic behavior:
+
+- **Exclude files**: Use `global-exclude` or `exclude` to remove files that are SCM-tracked but shouldn't be in the package
+- **Include additional files**: Use `include` to add files that aren't SCM-tracked
+
+```text title="MANIFEST.in"
+# Exclude development files
+exclude *.nix
+exclude .pre-commit-config.yaml
+global-exclude *.pyc
+
+# Include additional files not in SCM
+include data/special-file.dat
+```
+
+**Example of what gets included automatically**:
+
+- All files tracked by Git/Mercurial in your repository
+- Includes source code, data files, documentation, etc.
+- Excludes untracked files and files ignored by your SCM
+
+#### Troubleshooting
+
+**Too many files in your sdist?**
+
+1. Check what's being included: `python -m setuptools_scm ls`
+2. Use `MANIFEST.in` to exclude unwanted files:
+   ```text
+   exclude development-file.txt
+   global-exclude *.log
+   prune unnecessary-directory/
+   ```
+
+**Files missing from your sdist?**
+
+1. Ensure files are tracked by your SCM: `git add` or `hg add`
+2. For non-SCM files, add them via `MANIFEST.in`:
+   ```text
+   include important-file.txt
+   recursive-include data *.json
+   ```
+
+**Disable automatic file finding** (not recommended):
+
+If you need to completely disable setuptools-scm's file finder (not recommended), you would need to uninstall setuptools-scm from your build environment and handle versioning differently.
+
 `MANIFEST.in` may still be used: anything defined there overrides the hook.
 This is mostly useful to exclude files tracked in your SCM from packages,
 although in principle it can be used to explicitly include non-tracked files too.