Pants provides several goals to provide insights into your project's structure.
Tip: Use
xargs
to pipe these goals into other Pants commandsFor example:
$ ./pants dependees project:lib | xargs ./pants test
See Advanced target selection for more info and other techniques to use the results.
list
- find your project's targets
list
- find your project's targetslist
will find all targets that match the arguments.
For example, to show all targets in your project:
$ ./pants list ::
//:ansicolors
//:setuptools
helloworld:config
helloworld:config_file
...
filter
- find targets that match a predicate
filter
- find targets that match a predicatefilter
is like list
, but will only include targets that match the predicate(s).
Specify a predicate by using one of the below filter
options, like --target-type
. You can use a comma to OR multiple values, meaning that at least one member must be matched. You can repeat the option multiple times to AND each filter. You can prefix the filter with -
to negate the filter, meaning that the target must not be true for the filter.
Some examples:
# Only `python_library` targets.
./pants filter --target-type=python_library ::
# `python_library` or `python_tests` targets.
./pants filter --target-type='python_library,python_tests' ::
# `python_library` targets which have "type_checked" in their `tags` field.
./pants filter --target-type=python_library --tag-regex=type_checked ::
# Any target except for `python_library` targets
./pants filter --target-type='-python_library' ::
filter --target-type
filter --target-type
Each value should be the name of a target type, e.g. python_library
or resources
. Run ./pants help targets
to see what targets are registered.
filter --address-regex
filter --address-regex
Regex strings for the address, such as ^dir
or :util$
.
filter --tag-regex
filter --tag-regex
Regex strings for the tags
field. Alternatively, you can use the global --tags
option, which uses exact string matches instead of regex. See Advanced target selection.
dependencies
- find a target's dependencies
dependencies
- find a target's dependenciesUse dependencies
to list all targets used directly by a target.
$ ./pants dependencies helloworld/util
//:setuptools
//:translate
helloworld/protos:protos
To include transitive dependenciesβmeaning the dependencies of the direct dependenciesβuse --transitive
:
$ ./pants dependencies --transitive helloworld/util
//:protobuf
//:requirements.txt
//:setuptools
//:translate
helloworld/protos:protos
You can also output your 3rdparty requirements (e.g. Python requirement strings) by using --type=3rdparty
or --type=source-and-3rdparty
:
$ ./pants dependencies --type=3rdparty helloworld/util
setuptools>=42.0.0
translate>=3.2.1
dependees
- find which targets depend on a target
dependees
- find which targets depend on a targetThe dependees
goal finds all targets that directly depend on the target you specify.
$ ./pants dependees helloworld/util
helloworld:config
helloworld/greet:greet
helloworld/util:tests
To include transitive dependeesβmeaning targets that don't directly depend on your target, but which depend on a target that does directly use your targetβuse --transitive
:
$ ./pants dependees --transitive helloworld/util
helloworld:config
helloworld:helloworld
helloworld:helloworld-awslambda
helloworld/greet:greet
helloworld/greet:tests
helloworld/util:tests
To include the original target itself, use --closed
:
$ ./pants dependees --closed helloworld/util
helloworld:config
helloworld/greet:greet
helloworld/util:tests
helloworld/util:util
Finally, we recommend --output-format=json
when using multiple input targets:
$ ./pants dependees --output-format=json helloworld/util helloworld/protos
{
"helloworld/protos:protos": [
"helloworld/util:util",
"helloworld:config"
],
"helloworld/util:util": [
"helloworld/greet:greet",
"helloworld/util:tests",
"helloworld:config"
]
}
Tip: use
dependees
when starting a big migrationRunning
./pants dependees --transitive --output-format=json ::
will allow you to find the most-depended on code in your project, such as util code. Often, you will want to convert these targets first.For example, do this when migrating from Python 2 to Python 3, or adding an incremental type checker like MyPy or TypeScript to your project.
filedeps
- find which files a target owns
filedeps
- find which files a target ownsfiledeps
outputs all of the files belonging to a target, based on its sources
field.
$ ./pants filedeps --no-absolute helloworld/util
helloworld/util/BUILD
helloworld/util/config_loader.py
helloworld/util/lang.py
To output absolute paths, use the option --absolute
:
$ ./pants filedeps --absolute helloworld/util
/Users/pantsbuild/example-python/helloworld/util/BUILD
/Users/pantsbuild/example-python/helloworld/util/config_loader.py
/Users/pantsbuild/example-python/helloworld/util/lang.py
To include the files used by dependencies (including transitive dependencies), use --transitive
:
$ ./pants filedeps --transitive helloworld/util
BUILD
helloworld/protos/BUILD
helloworld/protos/config.proto
helloworld/util/BUILD
helloworld/util/config_loader.py
helloworld/util/lang.py
requirements.txt
count-loc
- count lines of code
count-loc
- count lines of codecount-loc
counts the lines of code of the specified files by running the Succinct Code Counter tool.
$ ./pants count-loc '**/*.py' '**/*.proto'
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Language Files Lines Blanks Comments Code Complexity
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Python 13 155 50 22 83 5
Protocol Buffers 1 11 3 2 6 0
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Total 14 166 53 24 89 5
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
SCC has dozens of options. You can pass through options by either setting --scc-args
or using --
at the end of your command, like this:
./pants count-loc '**' -- --no-cocomo
See unexpected results? Set
pants_ignore
.By default, Pants will ignore all globs specified in your
.gitignore
, along withdist/
and any hidden files.To ignore additional files, add to the global option
pants_ignore
in yourpants.toml
, using the same syntax as.gitignore
files.For example:
[GLOBAL] pants_ignore.add = ["/ignore_this_dir/"]
Updated 4 months ago