See File arguments vs. target arguments for the normal techniques for telling Pants what to run on.
See Project introspection for queries that you can run and then pipe into another Pants run, such as running over certain target types.
Because Pants understands Git, it can find which files have changed since a certain commit through the
For example, to lint all uncommitted files, run:
./pants --changed-since=HEAD lint
To run against another branch, run:
./pants --changed-since=origin/main lint
--changed-since will only run over files directly changed. Often, though, you will want to run over any dependees of those changed files, meaning any targets that depend on the changed files. Use
--changed-dependees=transitive for this:
$ ./pants \ --changed-since=origin/main \ --changed-dependees=transitive \ test
Using a version control system other than Git?
Please message us on Slack or open a GitHub issue (see Community). We would be happy to look into adding support for your VCS, such as helping you with a PR to add support.
Every target type has a field called
tags, which allows you to add a sequence of strings. The strings can be whatever you'd like, such as
python_tests( name="integration", sources=["*_integration_test.py"], tags=["skip_lint", "integration_test"], )
You can then filter by tags with the global
--tag option, like this:
./pants --tag=integration_test list ::
To exclude certain tags, prefix with a
./pants --tag='-integration_test' list ::
You can even combine multiple includes and excludes:
./pants --tag='+type_checked,skip_lint' --tag='-integration_test' list ::
The global option
--spec-files allows you to pass a file containing target addresses and/or file names/globs to Pants.
Each entry must be separated by a new line.
$ ./pants --spec-files=targets.txt list
helloworld/lang/*.py helloworld/util helloworld/util:tests
Tip: centralized allow/block lists
tagsare useful for decentralized allow/block lists,
--spec-filesis useful when you want to define one single list of targets or files.
To pipe a Pants run, use your shell's
| pipe operator and
./pants dependees helloworld/util | xargs ./pants list
You can, of course, pipe multiple times:
$ ./pants dependees helloworld/util | \ xargs ./pants filter --target-type=python_source | \ xargs ./pants lint
Sometimes, you may want to reuse the output of a Pants run for multiple subsequent Pants runs. Rather than repeating
xargsmultiple times, you can generate a file through stdout redirection and
$ ./pants dependencies helloworld/util > util_dependencies.txt $ ./pants --spec-files=util_dependencies.txt lint
If you don't want to save the output to an actual file—such as to not pollute version control—you can use a variable and a named pipe:
$ TARGETS=$(./pants dependencies helloworld/util) $ ./pants --spec-files=<(echo $TARGETS) lint
You can leverage shell piping to partition the input targets into multiple shards.
For example, to split your Python tests into 10 shards, and select shard 0:
./pants list :: | xargs ./pants filter --target-type=python_test | awk 'NR % 10 == 0' | ./pants test
Updated over 1 year ago