[PATCH v3 1/5] Documentation: define protected configuration

["Glen Choo via GitGitGadget" <gitgitgadget@gmail.com>]

From: Glen Choo <chooglen@google.com>

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@github.com/
[2] https://lore.kernel.org/git/a0c89d0d-669e-bf56-25d2-cbb09b012e70@jeffhostetler.com/

Signed-off-by: Glen Choo <chooglen@google.com>
---
 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