Skip to content

Commit

Permalink
settings: add git cfg options for trace & debug
Browse files Browse the repository at this point in the history
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
  • Loading branch information
mjcheetham committed Apr 27, 2023
1 parent d6a4cf3 commit 50837bf
Show file tree
Hide file tree
Showing 4 changed files with 120 additions and 12 deletions.
84 changes: 84 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
20 changes: 12 additions & 8 deletions docs/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]**

---

Expand Down Expand Up @@ -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

Expand All @@ -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]**

---

Expand All @@ -125,7 +125,7 @@ export GCM_DEBUG=1

Defaults to disabled.

_No configuration equivalent._
**Also see: [credential.debug][credential-debug]**

---

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/shared/Core/Constants.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down
24 changes: 20 additions & 4 deletions src/shared/Core/Settings.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -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()
{
Expand All @@ -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;
Expand Down

0 comments on commit 50837bf

Please sign in to comment.