3 files changed, 120 insertions, 0 deletions

diff --git a/docs/internal-fs-layout.md b/docs/internal-fs-layout.md
index ea0070bfb..64fe74cbe 100644
--- a/docs/internal-fs-layout.md
+++ b/docs/internal-fs-layout.md
@@ -253,6 +253,7 @@ setting `REPO_CONFIG_DIR`.
 
 *   `.repoconfig/`: Repo's per-user directory for all random config files/state.
 *   `.repoconfig/config`: Per-user settings using [git-config] file format.
+    See [repoconfig.md](./repoconfig.md) for the available settings.
 *   `.repoconfig/keyring-version`: Cache file for checking if the gnupg subdir
     has all the same keys as the repo launcher.  Used to avoid running gpg
     constantly as that can be quite slow.
diff --git a/docs/repoconfig.md b/docs/repoconfig.md
new file mode 100644
index 000000000..aef92fdc6
--- /dev/null
+++ b/docs/repoconfig.md
@@ -0,0 +1,103 @@
+# repoconfig: User Configuration
+
+Repo keeps a small number of settings that apply to the current user rather
+than to one checkout.  They live in the per-user configuration file
+`~/.repoconfig/config`, which is separate from both git's own `~/.gitconfig`
+and the per-checkout settings stored in `.repo/manifests.git/config` (see
+[internal-fs-layout.md](./internal-fs-layout.md#Global-settings) for those).
+
+[TOC]
+
+## Location
+
+The file is `.repoconfig/config` inside the user's home directory.  The parent
+directory can be changed by setting the `REPO_CONFIG_DIR` environment variable,
+in which case repo reads `$REPO_CONFIG_DIR/.repoconfig/config` instead.
+
+The file is created on demand; it's fine for it to be missing.
+
+## Format
+
+The file uses the [git-config] syntax, so it can be edited by hand:
+
+```ini
+[sync]
+        smartsync = true
+```
+
+or managed with `git config` by pointing it at the file explicitly:
+
+```sh
+# Set a value.
+git config --file ~/.repoconfig/config sync.smartsync true
+
+# Read a value.
+git config --file ~/.repoconfig/config sync.smartsync
+
+# Remove a value.
+git config --file ~/.repoconfig/config --unset sync.smartsync
+```
+
+Boolean settings accept `true`/`yes` and `false`/`no`.
+
+Repo caches a parsed copy of the file in `.repoconfig/.repo_config.json`; it is
+refreshed automatically whenever `config` changes and can be safely deleted.
+
+## Settings
+
+### alias.*
+
+`alias.<name>` defines `repo <name>` as a shortcut for another subcommand,
+optionally with arguments, in the same way as git aliases:
+
+```ini
+[alias]
+        ss = sync -s
+        st = status -o
+```
+
+Aliases defined in a checkout's `.repo/config` take precedence over per-user
+ones.  Existing subcommands cannot be overridden by an alias.
+
+### sync
+
+#### smartsync
+
+`sync.smartsync` is a boolean that lets a user decide once, for all their
+checkouts, whether `repo sync` should [Smart Sync](./smart-sync.md) by
+default:
+
+```sh
+# Always Smart Sync, as if -s/--smart-sync were passed.
+git config --file ~/.repoconfig/config sync.smartsync true
+
+# Never Smart Sync by default, even if the manifest sets sync-smartsync="true".
+git config --file ~/.repoconfig/config sync.smartsync false
+
+# Remove the preference and go back to following the manifest.
+git config --file ~/.repoconfig/config --unset sync.smartsync
+```
+
+The effective behavior is resolved in this order; the first match wins:
+
+1.  Command line: `-s`/`--smart-sync`, `--no-smart-sync`, or `-t`/`--smart-tag`.
+2.  User config: `sync.smartsync` in `~/.repoconfig/config`.
+3.  Manifest: `sync-smartsync="true"` on the `<default>` element.
+4.  Otherwise, a regular ToT sync.
+
+So `sync.smartsync=false` turns off the manifest-driven default, but an
+explicit `repo sync -s`, `repo sync -t TAG` or `repo smartsync` still works.
+Likewise `sync.smartsync=true` is overridden by `--no-smart-sync`.
+
+A Smart Sync enabled by `sync.smartsync=true` is treated as an explicit
+request: it is subject to the same restrictions as `-s` (it is skipped when
+`-l`/`--local-only`, `-m`/`--manifest-name`, `-t`/`--smart-tag` or
+`--superproject-revision` is used), and a failure to obtain a manifest from
+the server fails the sync instead of silently falling back to ToT.
+
+`sync.smartsync` does not affect `-l`/`--local-only`: a local-only sync keeps
+whatever `smart_sync_override.xml` the previous network sync left behind.  See
+[smart-sync.md](./smart-sync.md#Client-Options) for details.
+
+
+[git-config]: https://git-scm.com/docs/git-config
diff --git a/docs/smart-sync.md b/docs/smart-sync.md
index 24f37461b..905a004a0 100644
--- a/docs/smart-sync.md
+++ b/docs/smart-sync.md
@@ -204,6 +204,10 @@ still fails the sync, as before. Options that specify an explicit target or
 manifest source (such as `-t`/`--smart-tag`, `-m`/`--manifest-name` or
 `--superproject-revision`) will also disable the default Smart Sync behavior.
 
+Users can override this manifest default on their workstation with the
+`sync.smartsync` user setting; see
+[Per-user default](#Per_user-default-sync_smartsync) below.
+
 ### --smart-sync / -s
 
 Explicitly enables Smart Sync. Repo will call
@@ -231,6 +235,18 @@ match the settings Android build environments automatically setup.
 Explicitly disables Smart Sync, overriding any `sync-smartsync="true"` setting
 declared in the manifest `<default>` element.
 
+### Per-user default (sync.smartsync)
+
+A user can decide once, for all their checkouts, whether `repo sync` should
+Smart Sync by default by setting the boolean `sync.smartsync` key in their
+[per-user repo config](./repoconfig.md#smartsync).
+
+Command line flags (`-s`, `--no-smart-sync`, `-t`) override the user setting,
+which in turn overrides the manifest's `sync-smartsync` default.  A Smart Sync
+enabled this way is treated as an explicit request, so it is subject to the
+same restrictions as `-s` and fails the sync if no manifest can be obtained
+from the server instead of silently falling back to ToT.
+
 ### --smart-tag=TAG / -t
 
 Repo will call `GetManifest(TAG)`.