Skip to main content
Version: 2.24 (prerelease)

shell_command

Execute any external tool for its side effects.

Example BUILD file:

shell_command(
    command="./my-script.sh --flag",
    tools=["tar", "curl", "cat", "bash", "env"],
    execution_dependencies=[":scripts"],
    output_files=["logs/my-script.log"],
    output_directories=["results"],
)

shell_sources(name="scripts")

Remember to add this target to the dependencies of each consumer, such as your python_tests or docker_image. When relevant, Pants will run your command and insert the outputs into that consumer's context.

The command may be retried and/or cancelled, so ensure that it is idempotent.

Backend: pants.backend.shell

command​

str
required

Shell command to execute.

The command is executed as 'bash -c <command>' by default. If you want to invoke a binary use exec -a $0 <binary> <args> as the command so that the binary gets the correct argv[0] set.

cache_scope​

'from_environment' | 'session' | 'success' | 'success_per_pantsd_restart' | None
default: 'from_environment'

Set the "cache scope" of the executed process to provided value. The cache scope determines for how long Pants will cache the result of the process execution (assuming no changes to files or dependencies invalidate the result in the meantime).

The valid values are:

  • from_environment: Use the default cache scope for the applicable environment in which the process will execute. This is success for all environments except for experimental_workspace_environment, in which case session cache scope will be used.

  • success: Cache successful executions of the process.

  • success_per_pantsd_restart: Cache successful executions of the process for the life of the applicable pantsd process.

  • session: Only cache the result for a single Pants session. This will usually be a single invocation of the pants tool.

description​

str | None
default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

environment​

str | None
default: '__local__'

Specify which environment target to consume environment-sensitive options from.

Once environments are defined in [environments-preview].names, you can specify the environment for this target by its name. Any fields that are defined in that environment will override the values from options set by pants.toml, command line values, or environment variables.

You can specify multiple valid environments by using parametrize. If __local__ is specified, Pants will fall back to the local_environment defined for the current platform, or no environment if no such environment exists.

execution_dependencies​

Iterable[str] | None
default: None

The execution dependencies for this command.

Dependencies specified here are those required to make the command complete successfully (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make the outputs of the command useful. Dependencies that are required to use the outputs produced by this command should be specified using the output_dependencies field.

If this field is specified, dependencies from output_dependencies will not be added to the execution sandbox.

See also output_dependencies and runnable_dependencies.

experimental_named_caches​

Dict[str, str] | None
default: None

Named caches to construct for the execution. See https://www.pantsbuild.org/docs/reference-global#named_caches_dir.

The keys of the mapping are the directory name to be created in the named caches dir. The values are the name of the symlink (relative to the sandbox root) in the sandbox which points to the subdirectory in the named caches dir

NOTE: The named caches MUST be handled with great care. Processes accessing the named caches can be run in parallel, and can be cancelled at any point in their execution (and potentially restarted). That means that every operation modifying the contents of the cache MUST be concurrency and cancellation safe.

extra_env_vars​

Iterable[str] | None
default: None

Additional environment variables to provide to the process.

Entries are strings in the form ENV_VAR=value to use explicitly; or just ENV_VAR to copy the value of a variable in Pants's own environment.

log_output​

bool
default: False

Set to true if you want the output logged to the console.

output_dependencies​

Iterable[str] | None
default: None

Any dependencies that need to be present (as transitive dependencies) whenever the outputs of this target are consumed (including as dependencies).

See also execution_dependencies and runnable_dependencies.

output_directories​

Iterable[str] | None
default: ()

Specify full directories (including recursive descendants) of output to capture, relative to the value of workdir.

For individual files, use output_files. At least one of output_files andoutput_directories must be specified.

Relative paths (including ..) may be used, as long as the path does not ascend further than the build root.

output_files​

Iterable[str] | None
default: ()

Specify the output files to capture, relative to the value of workdir.

For directories, use output_directories. At least one of output_files andoutput_directories must be specified.

Relative paths (including ..) may be used, as long as the path does not ascend further than the build root.

outputs_match_mode​

'all' | 'all_warn' | 'allow_empty' | 'at_least_one' | 'at_least_one_warn' | None
default: 'all_warn'

Configure whether all, or some, of the values in the output_files and output_directories fields must actually match the outputs generated by the invoked process. These values are called "globs". Outputs may be matched by more than one glob.

Valid values are:

  • all_warn: Log a warning if any glob fails to match an output. (In other words, all globs must match to avoid a warning.) This is the default value.

  • all: Ensure all globs match an output or else raise an error.

  • at_least_one_warn: Log a warning if none of the globs match an output.

  • at_least_one: Ensure at least one glob matches an output or else raise an error.

  • allow_empty: Allow empty digests (which means nothing was captured). This disables checking that globs match outputs.

path_env_modify​

'append' | 'off' | 'prepend' | None
default: 'prepend'

When executing the command of an adhoc_tool or shell_command target, Pants may augment the PATH environment variable with the location of any binary shims created for tools and for any runnable dependencies.

Modification of the PATH environment variable can be configured as follows: - prepend: Prepend the extra path components to any existing PATH value. - append: Append the extra path componenets to any existing PATH value. - off: Do not modify the existing PATH value.

root_output_directory​

str | None
default: '/'

Adjusts the location of files output by this target, when consumed as a dependency.

Values are relative to the build root, except in the following cases:

  • . specifies the location of the BUILD file.
  • Values beginning with ./ are relative to the location of the BUILD file.
  • / or the empty string specifies the build root.
  • Values beginning with / are also relative to the build root.

runnable_dependencies​

Iterable[str] | None
default: None

The runnable dependencies for this command.

Dependencies specified here are those required to exist on the PATH to make the command complete successfully (interpreters specified in a #! command, etc). Note that these dependencies will be made available on the PATH with the name of the target.

See also output_dependencies and execution_dependencies.

tags​

Iterable[str] | None
default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.

timeout​

int | None
default: 30

Command execution timeout (in seconds).

tools​

Iterable[str] | None
default: ()

Specify required executable tools that might be used.

Only the tools explicitly provided will be available on the search PATH, and these tools must be found on the paths provided by [shell-setup].executable_search_paths (which defaults to the system PATH).

workdir​

str | None
default: '.'

Sets the working directory for the process.

Values are relative to the build root, except in the following cases:

  • . specifies the location of the BUILD file.
  • Values beginning with ./ are relative to the location of the BUILD file.
  • / or the empty string specifies the build root.
  • Values beginning with / are also relative to the build root.

workspace_invalidation_sources​

Iterable[str] | None
default: None

Path globs for source files on which this target depends and for which any changes should cause this target's process to be re-executed. Unlike ordinary dependencies, the files referenced by workspace_invalidation_sources globs are not materialized into any execution sandbox and are referenced solely for cache invalidation purposes.

Note: This field is intended to work with the in-workspace execution environment configured by the workspace_environment target type. It should only be used when the configured environment for a target is a workspace_environment.

Implementation: Pants computes a digest of all of the files referenced by the provided globs and injects that digest into the process as an environment variable. Since environment variables are part of the cache key for a process's execution, any changes to the referenced files will change the digest and thus force re-exection of the process.