diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internal-fs-layout.md | 1 | ||||
| -rw-r--r-- | docs/repoconfig.md | 103 | ||||
| -rw-r--r-- | docs/smart-sync.md | 16 |
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)`. |