Update docs and errors to use XDG config path

README.md

@@ -243,14 +243,10 @@ cargo install --git https://github.com/martinvonz/jj.git --locked --bin jj jj-cl
 ## Initial configuration
 
 You may want to configure your name and email so commits are made in your name.
-Create a file at `~/.jjconfig.toml` and make it look something like
-this:
 
 ```shell script
-$ cat ~/.jjconfig.toml
+$ jj config set --user user.name "Martin von Zweigbergk"
-[user]
+$ jj config set --user user.email "martinvonz@google.com"
-name = "Martin von Zweigbergk"
-email = "martinvonz@google.com"
 ```
 
 ## Command-line completion

cli/src/cli_util.rs

@@ -1400,9 +1400,9 @@ See https://github.com/martinvonz/jj/blob/main/docs/working-copy.md#stale-workin
         {
             writeln!(
                 ui.warning(),
-                r#"Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, add something like the following to $HOME/.jjconfig.toml:
+                r#"Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, run:
-  user.name = "Some One"
+  jj config set --user user.name "Some One"
-  user.email = "someone@example.com""#
+  jj config set --user user.email someone@example.com""#
             )?;
         }
         Ok(())

cli/src/commands/mod.rs

@@ -187,13 +187,10 @@ impl ConfigArgs {
 /// Manage config options
 ///
 /// Operates on jj configuration, which comes from the config file and
-/// environment variables. Uses the config file at ~/.jjconfig.toml or
+/// environment variables.
-/// $XDG_CONFIG_HOME/jj/config.toml, unless overridden with the JJ_CONFIG
-/// environment variable, combined with repo config at .jj/repo/config.toml
-/// if present.
 ///
-/// For supported config options and more details about jj config, see
+/// For file locations, supported config options, and other details about jj
-/// https://github.com/martinvonz/jj/blob/main/docs/config.md.
+/// config, see https://github.com/martinvonz/jj/blob/main/docs/config.md.
 #[derive(clap::Subcommand, Clone, Debug)]
 enum ConfigSubcommand {
     #[command(visible_alias("l"))]

cli/src/config.rs

@@ -57,7 +57,7 @@ pub struct AnnotatedValue {
 /// Sources from the lowest precedence:
 /// 1. Default
 /// 2. Base environment variables
-/// 3. User config `~/.jjconfig.toml` or `$JJ_CONFIG`
+/// 3. [User config](https://github.com/martinvonz/jj/blob/main/docs/config.md#configuration)
 /// 4. Repo config `.jj/repo/config.toml`
 /// 5. TODO: Workspace config `.jj/config.toml`
 /// 6. Override environment variables

cli/tests/test_global_opts.rs

@@ -389,9 +389,9 @@ fn test_no_user_configured() {
         .assert()
         .success();
     insta::assert_snapshot!(get_stderr_string(&assert), @r###"
-    Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, add something like the following to $HOME/.jjconfig.toml:
+    Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, run:
-      user.name = "Some One"
+      jj config set --user user.name "Some One"
-      user.email = "someone@example.com"
+      jj config set --user user.email someone@example.com"
     "###);
     let assert = test_env
         .jj_cmd(&repo_path, &["describe", "-m", "without email"])
@@ -399,9 +399,9 @@ fn test_no_user_configured() {
         .assert()
         .success();
     insta::assert_snapshot!(get_stderr_string(&assert), @r###"
-    Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, add something like the following to $HOME/.jjconfig.toml:
+    Name and email not configured. Until configured, your commits will be created with the empty identity, and can't be pushed to remotes. To configure, run:
-      user.name = "Some One"
+      jj config set --user user.name "Some One"
-      user.email = "someone@example.com"
+      jj config set --user user.email someone@example.com"
     "###);
 }
 

docs/config.md

@@ -8,11 +8,12 @@ These are the config settings available to jj/Jujutsu.
 The config settings are loaded from the following locations. Less common ways to
 specify `jj` config settings are discussed in a later section.
 
-* `~/.jjconfig.toml` (global)
+* [The user config file]
 * `.jj/repo/config.toml` (per-repository)
 
 See the [TOML site] and the [syntax guide] for a description of the syntax.
 
+[The user config file]: #configuration
 [TOML site]: https://toml.io/en/
 [syntax guide]: https://toml.io/en/v1.0.0
 
@@ -511,10 +512,13 @@ executable on your system](https://facebook.github.io/watchman/docs/install)).
 
 Debugging commands are available under `jj debug watchman`.
 
-# Alternative ways to specify configuration settings
+# Configuration
 
-Instead of `~/.jjconfig.toml`, the config settings can be located under
+On all platforms, the user's global `jj` configuration file is located at either
-a platform-specific directory. It is an error for both of these files to exist.
+`~/.jjconfig.toml` (where `~` represents `$HOME` on Unix-likes, or
+`%USERPROFILE%` on Windows) or in a platform-specific directory. The
+platform-specific location is recommended for better integration with platform
+services. It is an error for both of these files to exist.
 
 | Platform | Value                                              | Example                                                   |
 | :------- | :------------------------------------------------- | :-------------------------------------------------------- |