Advanced target selection

See File arguments vs. target arguments for the normal techniques for telling Pants what to run on.

Running over changed files with --changed-since

Because Pants understands Git, it can find which files have changed since a certain commit through the --changed-since option.

For example, to lint all uncommitted files, run:

$ <<pantscmd>> --changed-since=HEAD lint

To run against another branch, run:

$ <<pantscmd>> --changed-since=origin/master lint

By default, --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-include-dependees=direct or --changed-include-dependees=transitive for this:

$ <<pantscmd>> \
  --changed-since=origin/master \
  --changed-include-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.

Tags: annotating targets

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 "integration_test" or "skip_lint".

python_tests(
    name="integration",
    sources=["*_integration_test.py"],
    tags=["skip_lint", "integration_test"],
)

You can then filter by tags with the global --tags option, like this:

$ <<pantscmd>> --tag=integration_test list ::

To exclude certain tags, prefix with a -:

$ <<pantscmd>> --tag='-integration_test' list ::

You can even combine multiple includes and excludes:

$ <<pantscmd>> --tag='+type_checked,skip_lint' --tags='-integration_test' list ::

--spec-file

The global option --spec-file allows you to pass a file containing either target addresses or file names/globs to Pants.

Each entry must be separated by a new line.

For example:

$ <<pantscmd>> --spec-file=targets.txt list
helloworld/util
helloworld/util:tests

helloworld/util
helloworld/util:tests

📘

Tip: centralized allow/block lists

Whereas tags are useful for decentralized allow/block lists, --spec-file is useful when you want to define one single list of targets or files.

Piping to other Pants runs

To pipe a Pants run, use Bash's | pipe operator and xargs:

$ ./pants dependees helloworld/util | xargs <<pantscmd>>  list

You can, of course, pipe multiple times:

$ <<pantscmd>> dependees helloworld/util | \
   xargs <<pantscmd>>  list | \
   xargs <<pantscmd>> lint

📘

Alternative: use --spec-file

Sometimes, you may want to reuse the output of a Pants run for multiple subsequent Pants runs. Rather than repeating xargs multiple times, you can generate a file through stdout redirection and --spec-file.

For example:

Bash

$ <<pantscmd>> dependencies helloworld/util > util_dependencies.txt
$ <<pantscmd>> --spec-file=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:

Bash

$ TARGETS=$(<<pantscmd>> dependencies helloworld/util)
$ <<pantscmd>> --spec-file=<(echo $TARGETS) lint