Hatch should explain why a file is included

I’ve recently adopted Hatch for a few projects and have found it challenging to understand and predict how files are included or excluded from distributions.

The number of different options that affect the contents of a distribution introduces significant cognitive overhead, and the interactions between them are not intuitive. These include artifacts, include, force-include, only-include, exclude, packages, and only-packages. Many of these also support negated rules.

This complexity is further compounded by the fact that these directives can be specified both at the [tool.hatch.build] level and within target-specific sections like [tool.hatch.build.targets.sdist], with unclear precedence and potential merging or shadowing behavior.

Some rules are also implicitly loaded from the VCS ignore file, unless the VCS ignore file is ignored with ignore-vcs.

It would be very useful to have a tool like hatch explain file.py that lists the set of rules applied to the path and ultimately whether it was included or excluded.

As a concrete example, I tried the following configuration, which tries to be as explicit as possible that I do not want to include .gitignore in my source distribution (because the file does nothing outside of a git repository, and it lists files that have been excluded from the source distribution anyway). However, the file still ends up in the tarball.

[tool.hatch.build.targets.sdist]
only-include = [
  "script.py",
  "pyproject.toml",
  "README.md",
  "LICENSE",
]
exclude = [
  ".gitignore",
]