[PATCH 1/2] fetch doc: note "pushurl" caveat about "credentialsInUrl", elaborate

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

Amend the documentation and release notes entry for the
"fetch.credentialsInUrl" feature added in 6dcbdc0d661 (remote: create
fetch.credentialsInUrl config, 2022-06-06), it currently doesn't
detect passwords in `remote.<name>.pushurl` configuration. We
shouldn't lull users into a false sense of security, so we need to
mention that prominently.

This also elaborates and clarifies the "exposes the password in
multiple ways" part of the documentation. As noted in [1] a user
unfamiliar with git's implementation won't know what to make of that
scary claim, e.g. git hypothetically have novel git-specific ways of
exposing configured credentials.

The reality is that this configuration is intended as an aid for users
who can't fully trust their OS's or system's security model, so lets
say that's what this is intended for, and mention the most common ways
passwords stored in configuration might inadvertently get exposed.

1. https://lore.kernel.org/git/220524.86ilpuvcqh.gmgdl@evledraar.gmail.com/

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/RelNotes/2.37.0.txt |  4 +++-
 Documentation/config/fetch.txt    | 34 +++++++++++++++++++++++++------
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/Documentation/RelNotes/2.37.0.txt b/Documentation/RelNotes/2.37.0.txt
index 8f1ff3a5961..39ca3606dec 100644
--- a/Documentation/RelNotes/2.37.0.txt
+++ b/Documentation/RelNotes/2.37.0.txt
@@ -55,7 +55,9 @@ UI, Workflows & Features
  * Update the doctype written in gitweb output to xhtml5.
 
  * The "fetch.credentialsInUrl" configuration variable controls what
-   happens when a URL with embedded login credential is used.
+   happens when a URL with embedded login credential is used on either
+   "fetch" or "push". Credentials are currently only detected in
+   `remote.<name>.url` config, not `remote.<name>.pushurl`.
 
 
 Performance, Internal Implementation, Development Support etc.
diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt
index 0db7fe85bb8..827961059f8 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.txt
@@ -98,12 +98,34 @@ fetch.writeCommitGraph::
 	`git push -f`, and `git log --graph`. Defaults to false.
 
 fetch.credentialsInUrl::
-	A URL can contain plaintext credentials in the form
-	`<protocol>://<user>:<password>@<domain>/<path>`. Using such URLs
-	is not recommended as it exposes the password in multiple ways,
-	including Git storing the URL as plaintext in the repository config.
-	The `fetch.credentialsInUrl` option provides instruction for how Git
-	should react to seeing such a URL, with these values:
+	A configured URL can contain plaintext credentials in the form
+	`<protocol>://<user>:<password>@<domain>/<path>`. You may want
+	to warn or forbid the use of such configuration (in favor of
+	using linkgit:git-credential[1]).
++
+Note that this is currently limited to detecting credentials in
+`remote.<name>.url` configuration, it won't detect credentials in
+`remote.<name>.pushurl` configuration.
++
+You might want to enable this to prevent inadvertent credentials
+exposure, e.g. because:
++
+* The OS or system where you're running git may not provide way way or
+  otherwise allow you to configure the permissions of the
+  configuration file where the username and/or password are stored.
+* Even if it does, having such data stored "at rest" might expose you
+  in other ways, e.g. a backup process might copy the data to another
+  system.
+* The git programs will pass the full URL to one another as arguments
+  on the command-line, meaning the credentials will be exposed to oher
+  users on OS's or systems that allow other users to see the full
+  process list of other users. On linux the "hidepid" setting
+  documented in procfs(5) allows for configuring this behavior.
++
+If such concerns don't apply to you then you probably don't need to be
+concerned about credentials exposure due to storing that sensitive
+data in git's configuration files. If you do want to use this, set
+`fetch.credentialsInUrl` to one of these values:
 +
 * `allow` (default): Git will proceed with its activity without warning.
 * `warn`: Git will write a warning message to `stderr` when parsing a URL
-- 
2.36.1.1239.gfba91521d90