Deprecate the --config-override option. (pantsbuild#4715)

Alias `--pants-config-files` to `-c` and update various help docs to
point to the short form.

pants.daemon.ini

@@ -5,19 +5,19 @@
 # Development Usage:
 #
 #    # Launch the daemon via an initial invocation with `-ldebug` for better logging:
-#    $ ./pants -ldebug --config-override=pants.daemon.ini help
+#    $ ./pants -ldebug -c=pants.daemon.ini help
 #
 #    # In another window, tail the pantsd log file:
 #    $ tail -F .pants.d/pantsd/pantsd.log
 #
 #    # Populate the resident scheduler with an initial pantsd-based run:
-#    $ ./pants --config-override=pants.daemon.ini list 3rdparty::
+#    $ ./pants -c=pants.daemon.ini list 3rdparty::
 #
 #    # Re-run to utilize the buildgraph caching:
-#    $ ./pants --config-override=pants.daemon.ini list 3rdparty::
+#    $ ./pants -c=pants.daemon.ini list 3rdparty::
 #
 #    # Kill pantsd and watchman:
-#    $ ./pants -ldebug --config-override=pants.daemon.ini clean-all
+#    $ ./pants -ldebug -c=pants.daemon.ini clean-all
 #
 # You can also export this for all pants runs using environment variables:
 #

src/docs/howto_develop.md

@@ -122,7 +122,7 @@ To (re-)generate a `pants.pex` you then run these 2 commands:
 2. In your own repo the following command will create a locally built `pants.pex` for all platforms:
 
         :::bash
-        $ /tmp/pantsbuild/pants --config-override=pants-production.ini clean-all binary //:pants
+        $ /tmp/pantsbuild/pants -c=pants-production.ini clean-all binary //:pants
 
 The resulting `pants.pex` will be in the `dist/` directory:
 

src/docs/options.md

@@ -230,15 +230,15 @@ command line:
 Sometimes it's convenient to keep `.ini` settings in more than one file. Perhaps you usually
 operate Pants in one "mode", but occasionally need to use a tweaked set of settings.
 
-Use the `--pants-config-files` command-line option to specify a second `.ini` file. Each of
-this `.ini` file's values override the corresponding value in `pants.ini`, if any.
+Use the `--pants-config-files` command-line option (`-c` for short) to specify a second `.ini` file.
+Each of this `.ini` file's values override the corresponding value in `pants.ini`, if any.
 For example, if your `pants.ini` contains the section
 
     [test.junit]
     coverage_html_open: True
     debug: False
 
-...and you invoke `--pants-config-files=quick.ini` and your `quick.ini` says
+...and you invoke `-c=quick.ini` and your `quick.ini` says
 
     [test.junit]
     coverage_html_open: False
@@ -251,10 +251,9 @@ For example, if your `pants.ini` contains the section
     skip: True
     debug: False
 
-Note that `--pants-config-files` is a list-valued option, so all the
-idioms of lists work. You can add a third file with another invocation
-of `--pants-config-files=<path>`, or you can replace the standard one
-entirely with `--pants-config-files=[<list>]`.
+Note that `--pants-config-files` is a list-valued option, so all the idioms of lists work. You can
+add a third file with another invocation of `-c=<path>`, or you can replace the standard one
+entirely with `-c=[<list>]`.
 
 Troubleshooting Config Files
 ----------------------------

src/python/pants/init/plugin_resolver.py

@@ -114,7 +114,7 @@ def _options(self):
 
     # Ignore command line flags since we'd blow up on any we don't understand (most of them).
     # If someone wants to bootstrap plugins in a one-off custom way they'll need to use env vars
-    # or a --config-override pointing to a custom pants.ini snippet.
+    # or a --pants-config-files pointing to a custom pants.ini snippet.
     defaulted_only_options = options.drop_flag_values()
 
     GlobalOptionsRegistrar.register_options_on_scope(defaulted_only_options)

src/python/pants/option/global_options.py

@@ -94,15 +94,14 @@ def register_bootstrap_options(cls, register):
              help='The directory to use for tracking subprocess metadata, if any. This should '
                   'live outside of the dir used by `--pants-workdir` to allow for tracking '
                   'subprocesses that outlive the workdir data (e.g. `./pants server`).')
-    register('--pants-config-files', advanced=True, type=list,
+    register('-c', '--pants-config-files', advanced=True, type=list,
              default=[get_default_pants_config_file()], help='Paths to Pants config files.')
-    # TODO: Deprecate --config-override in favor of --pants-config-files.
-    # But only once we're able to both append and override list-valued options, as there are
-    # use-cases for both here.
-    # TODO: Deprecate the --pantsrc/--pantsrc-files options?  This would require being able
-    # to set extra config file locations in an initial bootstrap config file.
     register('--config-override', advanced=True, type=list, metavar='<path>',
+             removal_version='1.6.0.dev0',
+             removal_hint='Use -c=<second config file path> instead.',
              help='A second config file, to override pants.ini.')
+    # TODO: Deprecate the --pantsrc/--pantsrc-files options?  This would require being able
+    # to set extra config file locations in an initial bootstrap config file.
     register('--pantsrc', advanced=True, type=bool, default=True,
              help='Use pantsrc files.')
     register('--pantsrc-files', advanced=True, type=list, metavar='<path>',