diff --git a/docs/pyproject.md b/docs/pyproject.md
index 6d6fe27b650..5da05138b46 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -699,6 +699,15 @@ Poetry is clever enough to detect Python subpackages.
 Thus, you only have to specify the directory where your root package resides.
 {{% /note %}}
 
+{{% warning %}}
+If a VCS is being used, files matched by its ignore settings (for example, by
+`.gitignore` for Git) are excluded from the built distributions even when their
+parent directory is listed under `packages`. This can be surprising if a
+`packages` entry points at generated code or another path that is intentionally
+kept out of version control. To ship such files, add them back via
+[`include`]({{< relref "#exclude-and-include" >}}) with an explicit `format`.
+{{% /warning %}}
+
 ### exclude and include
 
 {{% note %}}