From 50837bf96eeff0be18ea878342bf6d3ac1424dc1 Mon Sep 17 00:00:00 2001 From: Matthew John Cheetham Date: Thu, 27 Apr 2023 09:49:16 -0700 Subject: [PATCH] settings: add git cfg options for trace & debug 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 --- docs/configuration.md | 84 ++++++++++++++++++++++++++++++++++++ docs/environment.md | 20 +++++---- src/shared/Core/Constants.cs | 4 ++ src/shared/Core/Settings.cs | 24 +++++++++-- 4 files changed, 120 insertions(+), 12 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index d77819731..d9122d6db 100644 --- a/docs/configuration.md +++ b/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 diff --git a/docs/environment.md b/docs/environment.md index 7c73965a7..02c548831 100644 --- a/docs/environment.md +++ b/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 diff --git a/src/shared/Core/Constants.cs b/src/shared/Core/Constants.cs index 5447981cd..f7c55c8a2 100644 --- a/src/shared/Core/Constants.cs +++ b/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"; diff --git a/src/shared/Core/Settings.cs b/src/shared/Core/Settings.cs index 284d4265c..ae4fb4eb4 100644 --- a/src/shared/Core/Settings.cs +++ b/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;