From b61a0d98061c6e46d26af3b703d3b36fa7cd8372 Mon Sep 17 00:00:00 2001
From: Matthew John Cheetham <mjcheetham@outlook.com>
Date: Wed, 2 Aug 2023 13:08:31 -0700
Subject: [PATCH] docs: add FAQ entry about (un)configure commands

Add an entry in the FAQs about what the `configure` and `unconfigure`
commands actually do to your Git configuration.
---
 docs/faq.md                                   | 46 +++++++++++++++++++
 .../resources/en.lproj/conclusion.html        |  1 +
 .../resources/en.lproj/welcome.html           |  1 +
 3 files changed, 48 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index cf761b1e8..3cc37cddc 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -230,6 +230,51 @@ demonstration purposes).
 5. Re-authorizing the application with the new scope (GCM should automatically
 initiate this flow for you next time access is requested).
 
+### Q: What do the `configure` and `unconfigure` commands do?
+
+#### `configure`
+
+The `configure` command will set up Git to use GCM exclusively as the credential
+helper. The `configure` command is automatically called by the installers for
+Windows and macOS, but you can also run it manually.
+
+It will also set Git to provide the full remote URL (including path) to
+credential helpers for Azure Repos remotes using the `dev.azure.com` URL format.
+This is required in order to be to able to correctly identify the correct
+authority for that Azure DevOps organization.
+
+Specifically, the `configure` command will modify your user Git configuration to
+include the following lines:
+
+```ini
+[credential]
+    helper =
+    helper = <path-to-gcm>
+[credential "https://dev.azure.com"]
+    useHttpPath = true
+```
+
+..where `<path-to-gcm>` is the absolute path to the GCM executable.
+
+The empty `helper =` line makes sure that existing credential helpers that may
+be set in the system Git configuration are not used. For more details see the
+[credential.helper][helper-config-docs].
+
+If you pass the `--system` option, the `configure` command will instead modify
+the system Git configuration. This is useful if you want to set up GCM for all
+users on a machine.
+
+#### `unconfigure`
+
+This command essentially undoes what the `configure` command does. It will check
+your Git configuration for the lines added by the `configure` command and remove
+them. The `unconfigure` command is run by the uninstaller for Windows and the
+uninstall script on macOS.
+
+On Windows, if run with the `--system` option, the `unconfigure` command will
+also ensure that the `credential.helper` setting in the system Git configuration
+is not removed and is left as `manager`, the default set by Git for Windows.
+
 [autodetect]: autodetect.md
 [azure-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops
 [bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html
@@ -251,6 +296,7 @@ initiate this flow for you next time access is requested).
 [gitlab-apps]: https://gitlab.com/-/profile/applications
 [gitlab-oauthapp-revoke]: ./img/gitlab-oauthapp-revoke.png
 [gitlab-oauthapp-revoked]: ./img/gitlab-oauthapp-revoked.png
+[helper-config-docs]: https://git-scm.com/docs/gitcredentials#Documentation/gitcredentials.txt-helper
 [multiple-users]: multiple-users.md
 [netconfig-http-proxy]: netconfig.md#http-proxy
 [linux-uninstall-from-src]: ./linux-fromsrc-uninstall.md
diff --git a/src/osx/Installer.Mac/resources/en.lproj/conclusion.html b/src/osx/Installer.Mac/resources/en.lproj/conclusion.html
index 7c82a0396..1fe9b197d 100644
--- a/src/osx/Installer.Mac/resources/en.lproj/conclusion.html
+++ b/src/osx/Installer.Mac/resources/en.lproj/conclusion.html
@@ -34,6 +34,7 @@ <h2>Uninstall</h2>
             <h2>Resources</h3>
             <ul>
                 <li><a href="https://aka.ms/gcm">Project homepage</a></li>
+                <li><a href="https://aka.ms/gcm/faq">Frequently asked questions</a></li>
                 <li><a href="https://aka.ms/gcm/config">Configuration options</a></li>
             </ul>
         </div>
diff --git a/src/osx/Installer.Mac/resources/en.lproj/welcome.html b/src/osx/Installer.Mac/resources/en.lproj/welcome.html
index e13600575..a5adeb79e 100644
--- a/src/osx/Installer.Mac/resources/en.lproj/welcome.html
+++ b/src/osx/Installer.Mac/resources/en.lproj/welcome.html
@@ -28,6 +28,7 @@ <h2>Installation notes</h2>
             <h2>Learn more</h2>
             <ul>
                 <li><a href="https://aka.ms/gcm">Project homepage</a></li>
+                <li><a href="https://aka.ms/gcm/faq">Frequently asked questions</a></li>
             </ul>
         </div>
     </body>