Skip to main content
Version: 2.31 (dev)

run_shell_command

Run a script in the workspace with dependencies packaged into a chroot.

This target is designed for quick, workspace-oriented interactive scripts that use tools from the system PATH.

Example BUILD file:

run_shell_command(
    command="./scripts/my-script.sh --data-files-dir={chroot}",
    execution_dependencies=["src/project/files:data"],
)

The command may use either {chroot} on the command line, or the $CHROOT environment variable to get the root directory for where any dependencies are located.

In contrast to shell_command, this target: - Uses tools from the system PATH (not explicit tools field) - Does not support output_files (outputs go directly to workspace) - Is simpler to use for quick workspace scripts

For more hermetic execution with explicit tool dependencies, consider using shell_command instead, which provides better reproducibility and caching.

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.

description​

str | None
default: None

A human-readable description of the target.

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

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.

See also runnable_dependencies.

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 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.

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.