Add Git configuration options for trace & debug (#1228)

Add options for enabling tracing and debugging in Git configuration.
Today the below options were only supported via environment variable:

 - `GCM_TRACE`
 - `GCM_TRACE_SECRETS`
 - `GCM_TRACE_MSAUTH`
 - `GCM_DEBUG`

Author: mjcheetham

docs/configuration.md

@@ -76,6 +76,86 @@ Defaults to enabled.
 
 ---
 
+### credential.trace
+
+Enables trace logging of all activities.
+Configuring Git and GCM to trace to the same location is often desirable, and
+GCM is compatible and cooperative with `GIT_TRACE`.
+
+#### Example
+
+```shell
+git config --global credential.trace /tmp/git.log
+```
+
+If the value of `credential.trace` is a full path to a file in an existing
+directory, logs are appended to the file.
+
+If the value of `credential.trace` is `true` or `1`, logs are written to
+standard error.
+
+Defaults to disabled.
+
+**Also see: [GCM_TRACE][gcm-trace]**
+
+---
+
+### credential.traceSecrets
+
+Enables tracing of secret and sensitive information, which is by default masked
+in trace output. Requires that `credential.trace` is also enabled.
+
+#### Example
+
+```shell
+git config --global credential.traceSecrets true
+```
+
+If the value of `credential.traceSecrets` is `true` or `1`, trace logs will include
+secret information.
+
+Defaults to disabled.
+
+**Also see: [GCM_TRACE_SECRETS][gcm-trace-secrets]**
+
+---
+
+### credential.traceMsAuth
+
+Enables inclusion of Microsoft Authentication library (MSAL) logs in GCM trace
+output. Requires that `credential.trace` is also enabled.
+
+#### Example
+
+```shell
+git config --global credential.traceMsAuth true
+```
+
+If the value of `credential.traceMsAuth` is `true` or `1`, trace logs will
+include verbose MSAL logs.
+
+Defaults to disabled.
+
+**Also see: [GCM_TRACE_MSAUTH][gcm-trace-msauth]**
+
+---
+
+### credential.debug
+
+Pauses execution of GCM at launch to wait for a debugger to be attached.
+
+#### Example
+
+```shell
+git config --global credential.debug true
+```
+
+Defaults to disabled.
+
+**Also see: [GCM_DEBUG][gcm-debug]**
+
+---
+
 ### credential.provider
 
 Define the host provider to use when authenticating.
@@ -682,6 +762,7 @@ git config --global credential.azreposCredentialType oauth
 [gcm-bitbucket-authmodes]: environment.md#GCM_BITBUCKET_AUTHMODES
 [gcm-credential-cache-options]: environment.md#GCM_CREDENTIAL_CACHE_OPTIONS
 [gcm-credential-store]: environment.md#GCM_CREDENTIAL_STORE
+[gcm-debug]: environment.md#GCM_DEBUG
 [gcm-dpapi-store-path]: environment.md#GCM_DPAPI_STORE_PATH
 [gcm-github-authmodes]: environment.md#GCM_GITHUB_AUTHMODES
 [gcm-gitlab-authmodes]:environment.md#GCM_GITLAB_AUTHMODES
@@ -693,6 +774,9 @@ git config --global credential.azreposCredentialType oauth
 [gcm-namespace]: environment.md#GCM_NAMESPACE
 [gcm-plaintext-store-path]: environment.md#GCM_PLAINTEXT_STORE_PATH
 [gcm-provider]: environment.md#GCM_PROVIDER
+[gcm-trace]: environment.md#GCM_TRACE
+[gcm-trace-secrets]: environment.md#GCM_TRACE_SECRETS
+[gcm-trace-msauth]: environment.md#GCM_TRACE_MSAUTH
 [usage]: usage.md
 [git-config-http-proxy]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy
 [http-proxy]: netconfig.md#http-proxy

docs/environment.md

@@ -39,9 +39,9 @@ logs are appended to the file.
 
 If the value of `GCM_TRACE` is `true` or `1`, logs are written to standard error.
 
-Defaults to tracing disabled.
+Defaults to disabled.
 
-_No configuration equivalent._
+**Also see: [credential.trace][credential-trace]**
 
 ---
 
@@ -71,14 +71,14 @@ secret information.
 
 Defaults to disabled.
 
-_No configuration equivalent._
+**Also see: [credential.traceSecrets][credential-trace-secrets]**
 
 ---
 
 ### GCM_TRACE_MSAUTH
 
-Enables inclusion of Microsoft Authentication libraries (ADAL, MSAL) logs in GCM
-trace output. Requires that `GCM_TRACE` is also enabled.
+Enables inclusion of Microsoft Authentication library (MSAL) logs in GCM trace
+output. Requires that `GCM_TRACE` is also enabled.
 
 #### Example
 
@@ -97,11 +97,11 @@ export GCM_TRACE_MSAUTH=1
 ```
 
 If the value of `GCM_TRACE_MSAUTH` is `true` or `1`, trace logs will include
-verbose ADAL/MSAL logs.
+verbose MSAL logs.
 
 Defaults to disabled.
 
-_No configuration equivalent._
+**Also see: [credential.traceMsAuth][credential-trace-msauth]**
 
 ---
 
@@ -125,7 +125,7 @@ export GCM_DEBUG=1
 
 Defaults to disabled.
 
-_No configuration equivalent._
+**Also see: [credential.debug][credential-debug]**
 
 ---
 
@@ -840,6 +840,7 @@ export GCM_AZREPOS_CREDENTIALTYPE="oauth"
 [credential-bitbucketauthmodes]: configuration.md#credentialbitbucketAuthModes
 [credential-cacheoptions]: configuration.md#credentialcacheoptions
 [credential-credentialstore]: configuration.md#credentialcredentialstore
+[credential-debug]: configuration.md#credentialdebug
 [credential-dpapi-store-path]: configuration.md#credentialdpapistorepath
 [credential-githubauthmodes]: configuration.md#credentialgitHubAuthModes
 [credential-gitlabauthmodes]: configuration.md#credentialgitLabAuthModes
@@ -852,6 +853,9 @@ export GCM_AZREPOS_CREDENTIALTYPE="oauth"
 [credential-plain-text-store]: configuration.md#credentialplaintextstorepath
 [credential-provider]: configuration.md#credentialprovider
 [credential-stores]: credstores.md
+[credential-trace]: configuration.md#credentialtrace
+[credential-trace-secrets]: configuration.md#credentialtracesecrets
+[credential-trace-msauth]: configuration.md#credentialtracemsauth
 [default-values]: enterprise-config.md
 [freedesktop-ss]: https://specifications.freedesktop.org/secret-service/
 [gcm]: usage.md

src/shared/Core/Constants.cs

@@ -122,6 +122,10 @@ public static class Credential
             {
                 public const string SectionName = "credential";
                 public const string Helper      = "helper";
+                public const string Trace       = "trace";
+                public const string TraceSecrets = "traceSecrets";
+                public const string TraceMsAuth = "traceMsAuth";
+                public const string Debug       = "debug";
                 public const string Provider    = "provider";
                 public const string Authority   = "authority";
                 public const string AllowWia    = "allowWindowsAuth";

src/shared/Core/Settings.cs

@@ -475,7 +475,11 @@ protected virtual bool TryGetExternalDefault(string section, string scope, strin
 
         public Uri RemoteUri { get; set; }
 
-        public bool IsDebuggingEnabled => _environment.Variables.GetBooleanyOrDefault(KnownEnvars.GcmDebug, false);
+        public bool IsDebuggingEnabled =>
+            TryGetSetting(KnownEnvars.GcmDebug,
+                KnownGitCfg.Credential.SectionName,
+                KnownGitCfg.Credential.Debug,
+                out string str) && str.IsTruthy();
 
         public bool IsTerminalPromptsEnabled => _environment.Variables.GetBooleanyOrDefault(KnownEnvars.GitTerminalPrompts, true);
 
@@ -536,7 +540,11 @@ public bool IsInteractionAllowed
             }
         }
 
-        public bool GetTracingEnabled(out string value) => _environment.Variables.TryGetValue(KnownEnvars.GcmTrace, out value) && !value.IsFalsey();
+        public bool GetTracingEnabled(out string value) =>
+            TryGetSetting(KnownEnvars.GcmTrace,
+                KnownGitCfg.Credential.SectionName,
+                KnownGitCfg.Credential.Trace,
+                out value) && !value.IsFalsey();
 
         public Trace2Settings GetTrace2Settings()
         {
@@ -563,9 +571,17 @@ public Trace2Settings GetTrace2Settings()
             return settings;
         }
 
-        public bool IsSecretTracingEnabled => _environment.Variables.GetBooleanyOrDefault(KnownEnvars.GcmTraceSecrets, false);
+        public bool IsSecretTracingEnabled =>
+            TryGetSetting(KnownEnvars.GcmTraceSecrets,
+                KnownGitCfg.Credential.SectionName,
+                KnownGitCfg.Credential.TraceSecrets,
+                out string str) && str.IsTruthy();
 
-        public bool IsMsalTracingEnabled => _environment.Variables.GetBooleanyOrDefault(Constants.EnvironmentVariables.GcmTraceMsAuth, false);
+        public bool IsMsalTracingEnabled =>
+            TryGetSetting(KnownEnvars.GcmTraceMsAuth,
+                KnownGitCfg.Credential.SectionName,
+                KnownGitCfg.Credential.TraceMsAuth,
+                out string str) && str.IsTruthy();
 
         public string ProviderOverride =>
             TryGetSetting(KnownEnvars.GcmProvider, GitCredCfg.SectionName, GitCredCfg.Provider, out string providerId) ? providerId : null;