From: Glen Choo <chooglen@xxxxxxxxxx> For security reasons, some config variables are only trusted when they are specified in so-called 'protected configuration' [1]. A future commit will introduce another such config variable, so this is a good time to standardize the documentation and implementation of 'protected configuration'. Define 'protected configuration' as global and system-level config, and mark `safe.directory` 'Protected config only'. In a future commit, protected configuration will also include "-c". The following variables are intentionally not marked 'Protected config only': - `uploadpack.packObjectsHook` has the same security concerns as `safe.directory`, but due to a different implementation, it also respects the "-c" option. When protected configuration includes "-c", `upload.packObjectsHook` will be marked 'Protected config only'. - `trace2.*` happens to read the same config as `safe.directory` because they share an implementation. However, this is not for security reasons; it is because we want to start tracing so early that repository-level config and "-c" are not available [2]. This requirement is unique to `trace2.*`, so it does not makes sense for protected configuration to be subject to the same constraints. [1] For example, https://lore.kernel.org/git/6af83767-576b-75c4-c778-0284344a8fe7@xxxxxxxxxx/ [2] https://lore.kernel.org/git/a0c89d0d-669e-bf56-25d2-cbb09b012e70@xxxxxxxxxxxxxxxxx/ Signed-off-by: Glen Choo <chooglen@xxxxxxxxxx> --- Documentation/config.txt | 6 ++++++ Documentation/config/safe.txt | 19 ++++++++----------- Documentation/glossary-content.txt | 18 ++++++++++++++++++ 3 files changed, 32 insertions(+), 11 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index e284b042f22..07832de1a6c 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -369,6 +369,12 @@ inventing new variables for use in your own tool, make sure their names do not conflict with those that are used by Git itself and other popular tools, and describe them in your documentation. +Variables marked with '(Protected config only)' are only respected when +they are specified in protected configuration. This includes global and +system-level config, and excludes repository config, the command line +option `-c`, and environment variables. For more details, see the +'protected configuration' entry in linkgit:gitglossary[7]. + include::config/advice.txt[] include::config/core.txt[] diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.txt index ae0e2e3bdb4..c1caec460e8 100644 --- a/Documentation/config/safe.txt +++ b/Documentation/config/safe.txt @@ -1,21 +1,18 @@ safe.directory:: - These config entries specify Git-tracked directories that are - considered safe even if they are owned by someone other than the - current user. By default, Git will refuse to even parse a Git - config of a repository owned by someone else, let alone run its - hooks, and this config setting allows users to specify exceptions, - e.g. for intentionally shared repositories (see the `--shared` - option in linkgit:git-init[1]). + '(Protected config only) ' These config entries specify + Git-tracked directories that are considered safe even if they + are owned by someone other than the current user. By default, + Git will refuse to even parse a Git config of a repository owned + by someone else, let alone run its hooks, and this config + setting allows users to specify exceptions, e.g. for + intentionally shared repositories (see the `--shared` option in + linkgit:git-init[1]). + This is a multi-valued setting, i.e. you can add more than one directory via `git config --add`. To reset the list of safe directories (e.g. to override any such directories specified in the system config), add a `safe.directory` entry with an empty value. + -This config setting is only respected when specified in a system or global -config, not when it is specified in a repository config, via the command -line option `-c safe.directory=<path>`, or in environment variables. -+ The value of this setting is interpolated, i.e. `~/<path>` expands to a path relative to the home directory and `%(prefix)/<path>` expands to a path relative to Git's (runtime) prefix. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index aa2f41f5e70..a669983abd6 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -483,6 +483,24 @@ exclude;; head ref. If the remote <<def_head,head>> is not an ancestor to the local head, the push fails. +[[def_protected_config]]protected configuration:: + Protected configuration is configuration that Git considers more + trustworthy because it is unlikely to be tampered with by an + attacker. For security reasons, some configuration variables are + only respected when they are defined in protected configuration. ++ +Protected configuration includes: ++ +- system-level config, e.g. `/etc/git/config` +- global config, e.g. `$XDG_CONFIG_HOME/git/config` and + `$HOME/.gitconfig` ++ +Protected configuration excludes: ++ +- repository config, e.g. `$GIT_DIR/config` and + `$GIT_DIR/config.worktree` +- the command line option `-c` and its equivalent environment variables + [[def_reachable]]reachable:: All of the ancestors of a given <<def_commit,commit>> are said to be "reachable" from that commit. More -- gitgitgadget
