Skip to main content
Version: 2.21

Goals

The commands Pants runs.


Pants commands are known as goals, such as test and lint.

To see the current list of goals, run:

❯ pants help goals

You'll see more goals activated as you activate more backends.

Running goals

For example:

❯ pants count-loc project/app_test.py
───────────────────────────────────────────────────────────────────────────────
Language Files Lines Blanks Comments Code Complexity
───────────────────────────────────────────────────────────────────────────────
Python 1 374 16 19 339 6
───────────────────────────────────────────────────────────────────────────────
Total 1 374 16 19 339 6
───────────────────────────────────────────────────────────────────────────────

You can also run multiple goals in a single run of Pants, in which case they will run sequentially:

# Format all code, and then test it:
❯ pants fmt test ::

Finally, Pants supports running goals in a --loop. In this mode, all goals specified will run sequentially, and then Pants will wait until a relevant file has changed to try running them again.

# Re-run linters and testing continuously as files or their dependencies change:
❯ pants --loop lint test project/app_test.py

Use Ctrl+C to exit the --loop.

Goal arguments

Most goals require arguments to know what to work on.

You can use several argument types:

Argument typeSemanticsExample
File pathMatch the filepants test project/tests.py
Directory pathMatch everything in the directorypants test project/utils
:: globsMatch everything in the directory and belowpants test project::
Target addressesMatch the targetpants package project:tests

You can combine argument types, e.g. pants fmt src/go:: src/py/app.py.

You can address targets from the root of the repository by using plain :: and :. For example, pants package :: would produce artifacts for all packages declared in the whole repository and pants package : would produce artifacts only for those packages that are declared in the root directory of the repository.

To ignore something, prefix the argument with -. For example, pants test :: -project/integration_tests will run all your tests except for those in the directory project/integration_tests and pants package project:: -project: will package all targets in the subdirectories of the project directory, recursively, except for those declared directly under the project directory.

Tip: advanced target selection, such as running over changed files

See Advanced target selection for alternative techniques to specify which files/targets to run on.

Goal options

Many goals also have options to change how they behave. Every option in Pants can be set via an environment variable, config file, and the command line.

To see if a goal has any options, run pants help $goal or pants help-advanced $goal. See Command Line Help for more information.

For example:

❯ pants help test
17:20:14.24 [INFO] Remote cache/execution options updated: reinitializing scheduler...
17:20:15.36 [INFO] Scheduler initialized.

`test` goal options
-------------------

Run tests.

Config section: [test]

--[no-]test-debug
PANTS_TEST_DEBUG
debug
default: False
current value: False
Run tests sequentially in an interactive process. This is necessary, for example, when you
add breakpoints to your code.

...

You can then use the option by prefixing it with the goal name:

pants --test-debug test project/app_test.py

You can also put the option after the file/target arguments:

pants test project/app_test.py --test-debug

As a shorthand, if you put the option after the goal and before the file/target arguments, you can leave off the goal name in the flag:

pants test --debug project/app_test.py