Our options docs for v1.30 - vPresent (https://www.pantsbuild.org/docs/options#list-values) currently leave out the implicit scalar add form supported by flags and environment variables. The v1 docs explain this form though (https://v1.pantsbuild.org/options.html). Is the v2 doc omission by design for uniformity / decreased complexity of explanation or just an oversight? (where scalar form means

--a-list-option=a

appends a to the the list option just as the vector form

--a-list-option="+['a']"

does)

Good catch! I think we definitely want to document this. It's so useful.

Ok. I'll consider adding a warning too about the toml side of this. Its a toml restriction (tables vs values) and not a Pants one, but the fact you can't mix

a_list_option

with `a_list_option.add`/`a_list_option.remove`was not obvious to me at least and the error is a bit of a bomb blast:

$ git diff pants.toml
diff --git a/pants.toml b/pants.toml
index f147114fe..c01e1dc86 100644
--- a/pants.toml
+++ b/pants.toml
@@ -3,6 +3,7 @@ print_stacktrace = true
 
 # Enable our custom loose-source plugins.
 pythonpath = ["%(buildroot)s/pants-plugins"]
+backend_packages = []
 backend_packages.add = [
   "pants.backend.awslambda.python",
   "pants.backend.python",

Leads to:

$ ./pants -V
Duplicate keys! (line 7 column 1 char 143)
Traceback (most recent call last):
  File "/home/jsirois/.cache/pants/pants_dev_deps/Linux.py37.venv/lib/python3.7/site-packages/toml/decoder.py", line 780, in load_line
    currentlevel[pair[0]]
TypeError: list indices must be integers or slices, not str

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/jsirois/.cache/pants/pants_dev_deps/Linux.py37.venv/lib/python3.7/site-packages/toml/decoder.py", line 512, in loads
    multibackslash)
  File "/home/jsirois/.cache/pants/pants_dev_deps/Linux.py37.venv/lib/python3.7/site-packages/toml/decoder.py", line 783, in load_line
    raise ValueError("Duplicate keys!")
ValueError: Duplicate keys!

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/bin/pants_loader.py", line 100, in run_default_entrypoint
    exit_code = runner.run(start_time)
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/bin/pants_runner.py", line 66, in run
    env=self.env, args=self.args, allow_pantsrc=True
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/option/options_bootstrapper.py", line 163, in create
    pre_bootstrap_config = Config.load_file_contents(config_files_products)
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/option/config.py", line 69, in load_file_contents
    return cls._meta_load(opener, file_contents, seed_values=seed_values)
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/option/config.py", line 113, in _meta_load
    config_values = cls._parse_toml(content, normalized_seed_values)
  File "/home/jsirois/dev/pantsbuild/jsirois-pants/src/python/pants/option/config.py", line 137, in _parse_toml
    toml_values = cast(Dict[str, Any], toml.loads(config_content))
  File "/home/jsirois/.cache/pants/pants_dev_deps/Linux.py37.venv/lib/python3.7/site-packages/toml/decoder.py", line 514, in loads
    raise TomlDecodeError(str(err), original, pos)
toml.decoder.TomlDecodeError: Duplicate keys! (line 7 column 1 char 143)