# Option scopes
Options are partitioned into named _scopes_.
Some systemwide options belong in the _global scope_. For example, the `--level
` option, which controls the logging level, is in the global scope.
Other options belong to a _subsystem scope_. A _subsystem_ is simply a collection of related options, in a scope. For example, the `pytest
` subsystem contains options related to [Python's test framework pytest](🔗).
# Setting options
Every option can be set in the following ways, in order of precedence:
Via a command line flag.
In an environment variable.
In a config file (`
pants.toml
`).
If an option isn't set in one of these ways, it will take on a default value.
You can inspect both the current value and the default value by using `./pants help $scope
` or `./pants help-advanced $scope
`, e.g. `./pants help global
`.
## Command-line flags
Global options are set using an unqualified flag:
Subsystem options are set by providing the flag, with the name prefixed with the lower-case scope name and a dash. So for the option `--root-patterns
` in the scope `source
`:
## Environment variables
Global options are set using the environment variable `PANTS_{OPTION_NAME}
`:
Subsystem options are set using the environment variable
`PANTS_{SCOPE}_{OPTION_NAME}
`:
Note that the scope and option name are upper-cased, and any dashes in the option flag name are converted to underscores: `--multiword-name
` becomes `MULTIWORD_NAME
`.
## Config file entries
Global options are set in the `GLOBAL
` section of the config file:
Subsystem options are set in the section named for their scope:
Note that any dashes in the option flag name are converted to underscores: `--multiword-name
` becomes `multiword_name
`.
### Config file interpolation
Environment variables can be interpolated by using the syntax `%(env.ENV_VAR)s
`, e.g.:
Additionally, a few special values are pre-populated with the `%(var)s
` syntax:
`
%(buildroot)s
`: absolute path to the root of your repository`
%(homedir)s
`: equivalent to `$HOME
` or `~
``
%(user)s
`: equivalent to `$USER
``
%(pants_distdir)s
`: absolute path of the global option `--pants-distdir
`, which defaults to `{buildroot}/dist/
`
# Option types
Every option has a type, and any values you set must be of that type.
The option types are:
string
integer
bool
list
dict
A list-valued option may also declare a specific type for its members (e.g., a list of strings, or a list of integers).
## String and integer values
Standalone string and integer values are written without quotes. Any quotes will be considered part of the value, after shell escaping.
### Command-line flags:
### Environment variables:
### Config file entries:
## Boolean values
Boolean values can be specified using the special strings `true
` and `false
`. When specifying them via command-line flags you can also use the `--boolopt/--no-boolopt
` syntax.
### Command-line flags:
### Environment variables:
### Config file entries:
## List values
List values are parsed as Python list literals, so you must quote string values, and you may need to apply shell-level quoting and/or escaping, as required.
### Command-line flags:
You can also leave off the `[]
` to _append_ elements. So we can rewrite the above to:
### Environment variables:
Like with command-line flags, you can leave off the `[]
` to _append_ elements:
### Config file entries:
### Add/remove semantics
List values have some extra semantics:
A value can be preceded by `
+
`, which will _append_ the elements to the value obtained from lower-precedence sources.A value can be preceded by `
-
`, which will _remove_ the elements from the value obtained from lower-precedence sources.Multiple `
+
` and `-
` values can be provided, separated by commas.Otherwise, the value _replaces_ the one obtained from lower-precedence sources.
For example, if the value of `--listopt
` in `scope
` is set to `[1, 2]
` in a config file, then
will set the value to `[1, 2, 3, 4]
`.
will set the value to `[2, 3, 4]
`, and
will set the value to `[3, 4]
`.
Add/remove syntax in .toml files
The +/- syntax works in .toml files, but the entire value must be quoted:
This means that TOML treats the value as a string, instead of a TOML list.
Alternatively, you can use this syntactic sugar, which allows the values to be regular TOML lists:
But note that this only works in Pants's `
.toml
` config files, not in environment variables or command-line flags.
## Dict values
Dict values are parsed as Python dict literals on the command-line and environment variables, so you must quote string keys and values, and you may need to apply shell-level quoting and/or escaping, as required.
### Command-line flags:
### Environment variables:
### Config file entries:
You can use TOML's [nested table features](🔗). These are equivalent:
You can also use a string literal. Note the quotes:
### Add/replace semantics
A value can be preceded by `
+
`, which will _update_ the value obtained from lower-precedence sources with the entries.Otherwise, the value _replaces_ the one obtained from lower-precendence sources.
For example, if the value of `--dictopt
` in `scope
` is set to `{'foo', 1, 'bar': 2}
` in a config file, then
will set the value to `{'foo': 42, 'bar': 2, 'baz': 3}
`, and
will set the value to `{'foo': 42, 'baz': 3}
`.
# Reading individual option values from files
If an option value is too large or elaborate to use directly, or if you don't want to hard-code
values directly in `pants.toml
`, you can set the value of any option to the string
`@relative/path/from/repo/root/to/file
` (note the leading `@
`), and the value will be read
from that file.
If the file name ends with `.json
` or `.yaml
` then the file will be parsed as the relevant
format, which is useful for list- and dict-valued options.
Otherwise, the file is parsed as a literal as described above for each option type.
Note that you can use this feature on the command-line, in an env var, or in a config file:
Gotcha: If you modify the value file, you must manually restart pantsd
Until we resolve [this issue](🔗), changing the value in a file used with the `
@
` syntax as described above will not invalidate the build. For now, if such a file changes you will have to restart the Pants daemon manually. You can do so by `kill
`ing it (after using `ps -ef | grep pantsd
` to find its pid), or by running Pants once with `--no-pantsd
`.
# `.pants.rc
` file
You can set up personal Pants config files, using the same TOML syntax as `pants.toml
`. By default, Pants looks for the paths `/etc/pantsrc
`, `~/.pants.rc
`, and `.pants.rc
` in the repository root.
For example:
If you want to ban this feature, set `[GLOBAL].pantsrc = false
` in `pants.toml
`.