cli: deprecate --config-toml

Typical usage should now be covered by --config=NAME=VALUE.

Closes #3867

CHANGELOG.md

@@ -36,6 +36,9 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Deprecations
 
+* `--config-toml=TOML` is deprecated in favor of `--config=NAME=VALUE` and
+  `--config-file=PATH`.
+
 * The `Signature.username()` template method is deprecated for
   `Signature().email().local()`.
 

cli/src/cli_util.rs

@@ -3109,8 +3109,9 @@ pub struct EarlyArgs {
     /// constructs (such as array notation), quotes can be omitted.
     #[arg(long, value_name = "NAME=VALUE", global = true)]
     pub config: Vec<String>,
-    /// Additional configuration options (can be repeated)
-    #[arg(long, value_name = "TOML", global = true)]
+    /// Additional configuration options (can be repeated) (DEPRECATED)
+    // TODO: delete --config-toml in jj 0.31+
+    #[arg(long, value_name = "TOML", global = true, hide = true)]
     pub config_toml: Vec<String>,
     /// Additional configuration files (can be repeated)
     #[arg(long, value_name = "PATH", global = true, value_hint = clap::ValueHint::FilePath)]
@@ -3334,6 +3335,12 @@ fn handle_early_args(
     let args = EarlyArgs::from_arg_matches(&early_matches).unwrap();
 
     let old_layers_len = config.layers().len();
+    if !args.config_toml.is_empty() {
+        writeln!(
+            ui.warning_default(),
+            "--config-toml is deprecated; use --config or --config-file instead."
+        )?;
+    }
     config.extend_layers(parse_config_args(&args.merged_config_args(&early_matches))?);
 
     // Command arguments overrides any other configuration including the

cli/tests/cli-reference@.md.snap

@@ -197,7 +197,6 @@ To get started, see the tutorial at https://martinvonz.github.io/jj/latest/tutor
 * `--config <NAME=VALUE>` — Additional configuration options (can be repeated)
 
    The name should be specified as TOML dotted keys. The value should be specified as a TOML expression. If string value doesn't contain any TOML constructs (such as array notation), quotes can be omitted.
-* `--config-toml <TOML>` — Additional configuration options (can be repeated)
 * `--config-file <PATH>` — Additional configuration files (can be repeated)
 
 

cli/tests/test_completion.rs

@@ -83,7 +83,6 @@ fn test_bookmark_names() {
     --quiet	Silence non-primary command output
     --no-pager	Disable the pager
     --config	Additional configuration options (can be repeated)
-    --config-toml	Additional configuration options (can be repeated)
     --config-file	Additional configuration files (can be repeated)
     --help	Print help (see more with '--help')
     ");

cli/tests/test_global_opts.rs

@@ -591,10 +591,12 @@ fn test_early_args() {
 fn test_config_args() {
     let test_env = TestEnvironment::default();
     let list_config = |args: &[&str]| {
-        test_env.jj_cmd_success(
+        // Suppress deprecation warning of --config-toml
+        let (stdout, _stderr) = test_env.jj_cmd_ok(
             test_env.env_root(),
             &[&["config", "list", "--include-overridden", "test"], args].concat(),
-        )
+        );
+        stdout
     };
 
     std::fs::write(
@@ -649,6 +651,15 @@ fn test_config_args() {
     test.key3 = 'file2'
     "##);
 
+    let (stdout, stderr) = test_env.jj_cmd_ok(
+        test_env.env_root(),
+        &["config", "list", "foo", "--config-toml=foo='bar'"],
+    );
+    insta::assert_snapshot!(stdout, @"foo = 'bar'");
+    insta::assert_snapshot!(
+        stderr,
+        @"Warning: --config-toml is deprecated; use --config or --config-file instead.");
+
     let stderr = test_env.jj_cmd_failure(test_env.env_root(), &["config", "list", "--config=foo"]);
     insta::assert_snapshot!(stderr, @r"
     Config error: --config must be specified as NAME=VALUE
@@ -783,7 +794,6 @@ fn test_help() {
           --quiet                        Silence non-primary command output
           --no-pager                     Disable the pager
           --config <NAME=VALUE>          Additional configuration options (can be repeated)
-          --config-toml <TOML>           Additional configuration options (can be repeated)
           --config-file <PATH>           Additional configuration files (can be repeated)
     ");
 }

docs/config.md

@@ -1203,27 +1203,18 @@ env JJ_CONFIG=/dev/null jj log       # Ignores any settings specified in the con
 
 ### Specifying config on the command-line
 
-You can use one or more `--config`/`--config-toml`/`--config-file` options on
-the command line to specify additional configuration settings. This overrides
-settings defined in config files or environment variables. For example,
+You can use one or more `--config`/`--config-file` options on the command line
+to specify additional configuration settings. This overrides settings defined in
+config files or environment variables. For example,
 
 ```shell
-jj --config=ui.color=always --config-toml='ui.diff-editor="kdiff3"' split
+jj --config=ui.color=always --config=ui.diff-editor=kdiff3 split
 ```
 
-Config specified by `--config-toml` must be valid TOML. In particular, string
-values must be surrounded by quotes. To pass these quotes to `jj`, most shells
-require surrounding those quotes with single quotes as shown above. On the other
-hand, `--config` can accept a bare string value.
+Config value should be specified as a TOML expression. If string value doesn't
+contain any TOML constructs (such as array notation), quotes can be omitted.
 
-In `sh`-compatible shells, `--config-toml` can be used to merge entire TOML
-files with the config specified in `.jjconfig.toml`:
-
-```shell
-jj --config-toml="$(cat extra-config.toml)" log
-```
-
-This is equivalent to
+To load an entire TOML document, use `--config-file`:
 
 ```shell
 jj --config-file=extra-config.toml log