Hey! These docs are for version 2.10, which is no longer officially supported. Click here for the latest version, 2.17!

Pants commands are known as _goals_, such as `test` and `lint`.

To see the current list of goals, run:

You'll see more goals activated as you activate more [backends](🔗).

# Running goals

For example:

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

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.

Use `Ctrl+C` to exit the `--loop`.

# Goal arguments

Some simple goals—such as the `roots` goal—do not require arguments. But most goals require some arguments to work on.

For example, to run the `count-loc` goal, which counts lines of code in your repository, you need to provide a set of files and/or targets to run on:

Quoting file patterns

Note the single-quotes around the file pattern `'**'`. This is so that your shell doesn't attempt to expand the pattern, but instead passes it unaltered to Pants.

## File arguments vs. target arguments

Goal arguments can be of one of two types:

  • _File arguments_: file paths and/or globs.

  • _Target arguments_: addresses and/or address globs of [targets](🔗).

Typically you can just use file arguments, and not worry about targets.

Any goal can take either type of argument:

  • If a target argument is given, the goal acts on all the files in the matching targets.

  • If a file argument is given, Pants will map the file back to its containing target to read any necessary metadata.

File/target globs

For file arguments, use `'*'` and `'**'`, with the same semantics as the shell. Reminder: quote the argument if you want Pants to evaluate the glob, rather than your shell.

For target arguments, you can use:

  • `dir::`, where `::` means every target in the current directory and recursively in subdirectories.

  • `dir:`, where `:` means every target in that directory, but not subdirectories.

For example, `./pants list ::` will find every target in your project.

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:

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

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

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: