diff --git a/docs/docs/using-pants/key-concepts/targets-and-build-files.mdx b/docs/docs/using-pants/key-concepts/targets-and-build-files.mdx index 6a67757d982..4ee82eb3703 100644 --- a/docs/docs/using-pants/key-concepts/targets-and-build-files.mdx +++ b/docs/docs/using-pants/key-concepts/targets-and-build-files.mdx @@ -60,6 +60,21 @@ python_distribution( ) ``` +### Multiple BUILD files in a directory + +Typically, there would be one BUILD file in every directory containing source code and any other resources you +may want to use as part of your builds. Most likely, having just one BUILD file in a directory is also what you would want. +However, you can have multiple BUILD files in a single directory, if desired. When running a Pants goal, the contents +of the BUILD files will be merged making it possible to better group your targets. + +Storing targets in multiple BUILD files also makes it possible to dynamically include or exclude targets from your +builds. For example, you could include some experimental targets when running a Pants goal from a command line by +extending the list of recognized BUILD file patterns: + +```bash +$ pants --build-patterns="+['BUILD.experimental']" package project:app +``` + ## Target addresses A target is identified by its unique address, in the form `path/to/dir:name`. The above example has the addresses `helloworld/greet:tests` and `helloworld/greet:bin`.