Project introspection

Pants provides several goals in the pants.backend.project_info backend to provide insights into your project's structure. (Activated by default.)

📘

Tip: Use xargs to pipe these goals into other Pants commands

For example:

Bash

$ ./pants dependees project:lib | xargs <<pantscmd>> test

See Advanced target selection for more info and other techniques to use the results.

list - find your project's targets

list will find all targets that match the arguments.

For example, to show all targets in your project:

$ <<pantscmd>> list ::
//:ansicolors
//:setuptools
helloworld:config
helloworld:config_file
...

To see which target(s) own a specific file, use a file argument:

$ <<pantscmd>> list helloworld/main.py
helloworld:helloworld

dependencies - find a target's dependencies

Use dependencies to list all targets used directly by a target.

$ <<pantscmd>> dependencies helloworld/util
//:setuptools
//:translate
helloworld/protos:protos

To include transitive dependencies—meaning the dependencies of the direct dependencies—use --transitive:

$ <<pantscmd>> 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:

$ <<pantscmd>> dependencies --type=3rdparty helloworld/util
setuptools>=42.0.0
translate>=3.2.1

dependees - find which targets depend on a target

The dependees goal finds all targets that directly depend on the target you specify.

$ <<pantscmd>> 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:

$ <<pantscmd>> 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:

$ <<pantscmd>> 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:

$ <<pantscmd>> 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 migration

Running <<pantscmd>> 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 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

cloc - count lines of code

cloc counts the lines of code of the specified files by running this popular Perl script.

$ <<pantscmd>> cloc '**/*.py' '**/*.proto'
github.com/AlDanial/cloc v 1.80  T=0.02 s (951.5 files/s, 32255.1 lines/s)
--------------------------------------------------------------------------------
Language                      files          blank        comment           code
--------------------------------------------------------------------------------
Python                          11             50             22             83
Protocol Buffers                 1              3              2              6
-------------------------------------------------------------------------------
SUM:                            12             53             24             89
-------------------------------------------------------------------------------

Use the option --cloc-ignored to include information about files ignored by the script.

🚧

See unexpected results? Set pants_ignore.

By default, Pants will ignore all globs specified in your .gitignore, along with dist/ and any hidden files.

To ignore additional files, add to the global option pants_ignore in your pants.toml, using the same syntax as .gitignore files.

For example:

TOML

[GLOBAL]
pants_ignore.add = ["/ignore_this_dir/"]