From da3f10d6bd4f0924397a62ce6596cbc2b4ddfa87 Mon Sep 17 00:00:00 2001 From: wolf99 <281700+wolf99@users.noreply.github.com> Date: Sat, 14 May 2022 11:22:30 +0100 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Matthew John Cheetham --- README.md | 30 +++++++++--------- docs/architecture.md | 8 ++--- docs/autodetect.md | 6 ++-- docs/azrepos-users-and-tokens.md | 8 ++--- docs/bitbucket-development.md | 16 +++++----- docs/configuration.md | 52 ++++++++++++++++---------------- 6 files changed, 60 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 7e7f9f9ae8..e5182effa7 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ --- -[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][] that runs on Windows, macOS, and Linux. +[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][dotnet] that runs on Windows, macOS, and Linux. -Compared to Git's [built-in credential helpers][git-tools-credential-storage] (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps][], Azure DevOps Server (formerly Team Foundation Server), GitHub, and Bitbucket. +Compared to Git's [built-in credential helpers][git-tools-credential-storage] (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps][azure-devops], Azure DevOps Server (formerly Team Foundation Server), GitHub, and Bitbucket, and GitLab. Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows][gcm-for-windows] (GCM), and the Java-based [Git Credential Manager for Mac and Linux][gcm-for-mac-and-linux] (Java GCM), providing a consistent authentication experience across all platforms. @@ -14,9 +14,9 @@ Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential M Git Credential Manager is currently available for Windows, macOS, and Linux\*. GCM only works with HTTP(S) remotes; you can still use Git with SSH: -- [Azure DevOps SSH][] -- [GitHub SSH][] -- [Bitbucket SSH][] +- [Azure DevOps SSH][azure-devops-ssh] +- [GitHub SSH][github-ssh] +- [Bitbucket SSH][bitbucket-ssh] Feature|Windows|macOS|Linux -|:-:|:-:|:-: @@ -162,7 +162,7 @@ rm $(command -v git-credential-manager-core) ### Windows -GCM is included with [Git for Windows][], and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default. +GCM is included with [Git for Windows][git-for-windows], and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default. ![image][git-for-windows-screenshot] @@ -222,7 +222,7 @@ Git that are not compatible. Once it's installed and configured, Git Credential Manager is called implicitly by Git. You don't have to do anything special, and GCM isn't intended to be called directly by the user. -For example, when pushing (`git push`) to [Azure DevOps][], [Bitbucket][], or [GitHub][], a window will automatically open and walk you through the sign-in process. +For example, when pushing (`git push`) to [Azure DevOps][azure-devops], [Bitbucket][bitbucket], or [GitHub][github], a window will automatically open and walk you through the sign-in process. (This process will look slightly different for each Git host, and even in some cases, whether you've connected to an on-premises or cloud-hosted Git host.) Later Git commands in the same repository will re-use existing credentials or tokens that GCM has stored for as long as they're valid. @@ -263,12 +263,12 @@ This project follows [GitHub's Open Source Code of Conduct][gcm-coc]. We're [MIT][gcm-license] licensed. When using GitHub logos, please be sure to follow the [GitHub logo guidelines][github-logos]. -[Azure DevOps]: https://dev.azure.com/ -[Azure DevOps SSH]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops -[Bitbucket]: https://bitbucket.org -[Bitbucket SSH]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html +[azure-devops]: https://dev.azure.com/ +[azure-devops-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops +[bitbucket]: https://bitbucket.org +[bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html [build-status-badge]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg -[.NET]: https://dotnet.microsoft.com +[dotnet]: https://dotnet.microsoft.com [gcm]: https://github.com/GitCredentialManager/git-credential-manager [gcm-arch]: docs/architecture.md [gcm-azure-tokens]: docs/azrepos-users-and-tokens.md @@ -291,11 +291,11 @@ When using GitHub logos, please be sure to follow the [GitHub logo guidelines][g [gcm-usage]: docs/usage.md [gcm-windows-broker]: docs/windows-broker.md [gcm-wsl]: docs/wsl.md -[Git for Windows]: https://gitforwindows.org/ +[git-for-windows]: https://gitforwindows.org/ [git-for-windows-screenshot]: https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png [git-tools-credential-storage]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage -[GitHub]: https://github.com -[GitHub SSH]: https://help.github.com/en/articles/connecting-to-github-with-ssh +[github]: https://github.com +[github-ssh]: https://help.github.com/en/articles/connecting-to-github-with-ssh [github-logos]: https://github.com/logos [latest-release]: https://github.com/GitCredentialManager/git-credential-manager/releases/latest [ms-package-repos]: https://packages.microsoft.com/repos/ diff --git a/docs/architecture.md b/docs/architecture.md index 3828c4c2fe..e75576774e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,7 @@ library (C#). The library targets .NET Standard as well as .NET Framework. > **Note** > > The reason for also targeting .NET Framework directly is that the -> `Microsoft.Identity.Client` ([MSAL.NET][]) +> `Microsoft.Identity.Client` ([MSAL.NET][msal]) > library requires a .NET Framework target to be able to show the embedded web > browser auth pop-up on Windows platforms. > @@ -52,7 +52,7 @@ library (C#). The library targets .NET Standard as well as .NET Framework. > our own browser pop-up handling code on .NET meaning both Windows and > Mac. We haven't yet gotten around to exploring this. > -> See [GCM issue 113][] for more information. +> See [GCM issue 113][issue-113] for more information. The entry-point for GCM can be found in the `Git-Credential-Manager` project, a console application that targets both .NET and .NET Framework. @@ -81,7 +81,7 @@ helpers on Windows. We hope to be able to migrate the WPF/Windows only helpers to [Avalonia][] in order to gain cross-platform graphical user interface support. See -[GCM issue 136][] for up-to-date progress on this effort. +[GCM issue 136][issue-136] for up-to-date progress on this effort. ### Microsoft authentication @@ -147,7 +147,7 @@ Git Credential Manager maintains a set of known commands including GCM also maintains a set of known, registered host providers that implement the `IHostProvider` interface. Providers register themselves by adding an instance of the provider to the `Application` object via the `RegisterProvider` -method in [`Core.Program`][]. +method in [`Core.Program`][core-program]. The `GenericHostProvider` is registered last so that it can handle all other HTTP-based remotes as a catch-all, and provide basic username/password auth and detect the presence of Windows Integrated Authentication (Kerberos, NTLM, diff --git a/docs/autodetect.md b/docs/autodetect.md index dee8694e83..5be500e601 100644 --- a/docs/autodetect.md +++ b/docs/autodetect.md @@ -18,7 +18,7 @@ In order to detect which host provider to use for a self-hosted instance, each provider can provide some heuristic matching of the hostname. For example any hostname that begins "github.*" will be matched to the GitHub host provider. -If a heuristic matches incorrectly, you can always [explicitly configure][] +If a heuristic matches incorrectly, you can always [explicitly configure][explicit-config] GCM to use a particular provider. ## Remote URL probing @@ -28,7 +28,7 @@ URL and inspect HTTP response headers to try and detect a self-hosted instance. This network call is only performed if neither an exact nor fuzzy match by hostname can be made. Only one HTTP `HEAD` call is made per credential request -received by Git. To avoid this network call, please [explicitly configure][] +received by Git. To avoid this network call, please [explicitly configure][explicit-config] the host provider for your self-hosted instance. After a successful detection of the host provider, GCM will automatically set @@ -65,6 +65,6 @@ git config --global credential.ghe.example.com.provider github [`credential.autoDetectTimeout`]: configuration.md#credentialautodetecttimeout [`credential.provider`]: configuration.md#credentialprovider -[explicitly configure]: #manual-configuration +[explicit-config]: #manual-configuration [`GCM_AUTODETECT_TIMEOUT`]: environment.md#GCM_AUTODETECT_TIMEOUT [`GCM_PROVIDER`]: environment.md#GCM_PROVIDER diff --git a/docs/azrepos-users-and-tokens.md b/docs/azrepos-users-and-tokens.md index d528c6f87b..f510f6290d 100644 --- a/docs/azrepos-users-and-tokens.md +++ b/docs/azrepos-users-and-tokens.md @@ -18,7 +18,7 @@ Historically, the only option supported by the Azure Repos host provider was Azure DevOps Personal Access Tokens (PATs). These PATs are only used by Azure DevOps, and must be [managed through the Azure -DevOps user settings page][azure-devops-pats] or [REST API][]. +DevOps user settings page][azure-devops-pats] or [REST API][azure-devops-api]. PATs have a limited lifetime and new tokens must be created once they expire. In Git Credential Manager, when a PAT expired (or was manually revoked) this @@ -188,7 +188,7 @@ inherited). To associate a user account with a particular Git remote you must manually edit the remote URL using `git config` commands to include the username in the -[user information][] part of the URL. +[user information][rfc3986-s321] part of the URL. ```shell git config --local remote.origin.url https://alice-alt%40contoso.com@contoso.visualstudio.com/project/_git/repo @@ -221,5 +221,5 @@ fabrikam: [azure-devops-pats]: https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page [`credential.azreposCredentialType`]: configuration.md#credentialazreposcredentialtype [`GCM_AZREPOS_CREDENTIALTYPE`]: environment.md#GCM_AZREPOS_CREDENTIALTYPE -[REST API]: https://docs.microsoft.com/en-gb/rest/api/azure/devops/tokens/pats -[user information]: https://tools.ietf.org/html/rfc3986#section-3.2.1 +[azure-devops-api]: https://docs.microsoft.com/en-gb/rest/api/azure/devops/tokens/pats +[rfc3986-s321]: https://tools.ietf.org/html/rfc3986#section-3.2.1 diff --git a/docs/bitbucket-development.md b/docs/bitbucket-development.md index 23e3c6e963..2645cde8d4 100644 --- a/docs/bitbucket-development.md +++ b/docs/bitbucket-development.md @@ -7,15 +7,15 @@ Additionally Bitbucket supports App-specific passwords which can be used via Bas To enhance security Bitbucket offers optional Two-Factor Authentication (2FA). When 2FA is enabled username/password Basic Auth access to the REST APIs and to Git repositories is suspended. At that point users are left with the choice of username/apps-specific-password Basic Auth for REST APIs and Git interactions, OAuth for REST APIs and Git/Hg interactions or SSH for Git/HG interactions and one of the previous choices for REST APIs. SSH and REST API access are beyond the scope of this document. -Read about [Bitbucket's 2FA implementation][]. +Read about [Bitbucket's 2FA implementation][2fa-impl]. App-specific passwords are not particularly user friendly as once created Bitbucket hides their value, even from the owner. They are intended for use within application that talk to Bitbucket where application can remember and use the app-specific-password. -[Additional information][]. +[Additional information][additional-info]. OAuth is the intended authentication method for user interactions with HTTPS remote URL for Git repositories when 2FA is active. Essentially once a client application has an OAuth access token it can be used in place of a user's password. -Read more about information [Bitbucket's OAuth implementation][]. +Read more about information [Bitbucket's OAuth implementation][oauth-impl]. Bitbucket's OAuth implementation follows the standard specifications for OAuth 2.0, which is out of scope for this document. However it implements a comparatively rare part of OAuth 2.0 Refresh Tokens. @@ -30,7 +30,7 @@ This is explained in more detail below. ## Multiple User Accounts -Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or OAuth tokens, with usernames in the [Windows Credential Manager][] vault. +Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or OAuth tokens, with usernames in the [Windows Credential Manager][wincred-manager] vault. Depending on the circumstances this means either saving an explicit username in to the Windows Credential Manager/Vault or including the username in the URL used as the identifying key of entries in the Windows Credential Manager vault, i.e. using a key such as `git:https://mminns@bitbucket.org/` rather than `git:https://bitbucket.org`. This means that the Bitbucket implementation in the GCM can support multiple accounts, and usernames, for a single user against Bitbucket, e.g. a personal account and a work account. @@ -81,10 +81,10 @@ This will download and run a standalone instance of Bitbucket Server which can b Atlassian has [documentation][] on how to download and install their SDK. -[Additional information]:https://confluence.atlassian.com/display/BITBUCKET/App+passwords +[additional-info]:https://confluence.atlassian.com/display/BITBUCKET/App+passwords [atlas-run-standalone]: https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/ [bitbucket.org]: https://bitbucket.org -[Bitbucket's 2FA implementation]: https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html -[Bitbucket's OAuth implementation]: https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html +[2fa-impl]: https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html +[oauth-impl]: https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html [documentation]: https://developer.atlassian.com/server/framework/atlassian-sdk/ -[Windows Credential Manager]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx +[wincred-manager]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx diff --git a/docs/configuration.md b/docs/configuration.md index 585d394f3c..71ec3b0a80 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration options -[Git Credential Manager][] works out of the box for most users. +[Git Credential Manager][usage] works out of the box for most users. Git Credential Manager (GCM) can be configured using Git's configuration files, and follows all of the same rules Git does when consuming the files. @@ -9,7 +9,7 @@ Global configuration settings override system configuration settings, and local GCM honors several levels of settings, in addition to the standard local \> global \> system tiering Git uses. URL-specific settings or overrides can be applied to any value in the `credential` namespace with the syntax below. -Additionally, GCM respects several GCM-specific [environment variables][] **which take precedence over configuration options**. System administrators may also configure [default values][] for many settings used by GCM. +Additionally, GCM respects several GCM-specific [environment variables][envars] **which take precedence over configuration options**. System administrators may also configure [default values][enterprise-config] for many settings used by GCM. GCM will only be used by Git if it is installed and configured. Use `git config --global credential.helper manager-core` to assign GCM as your credential helper. Use `git config credential.helper` to see the current configuration. @@ -60,7 +60,7 @@ Define the host provider to use when authenticating. ID|Provider -|- -`auto` _(default)_|_\[automatic\]_ ([learn more][]) +`auto` _(default)_|_\[automatic\]_ ([learn more][autodetect]) `azure-repos`|Azure Repos `github`|GitHub `bitbucket`|Bitbucket @@ -85,7 +85,7 @@ git config --global credential.ghe.contoso.com.provider github > This setting is deprecated and should be replaced by `credential.provider` with the corresponding provider ID value. > -> See the [migration guide][] for more information. +> See the [migration guide][provider-migrate] for more information. Select the host provider to use when authenticating by which authority is supported by the providers. @@ -175,7 +175,7 @@ git config --global credential.tfsonprem123.allowWindowsAuth false > This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-config-http-proxy]. > -> See [HTTP Proxy][] for more information. +> See [HTTP Proxy][http-proxy] for more information. Configure GCM to use the a proxy for network operations. @@ -316,7 +316,7 @@ Select the type of credential store to use on supported platforms. Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset on Linux. -**Note:** See more information about configuring secret stores in [credential stores][]. +**Note:** See more information about configuring secret stores in [cred-stores][]. Value|Credential Store|Platforms -|-|- @@ -324,9 +324,9 @@ _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|- `wincredman`|Windows Credential Manager (not available over SSH).|Windows `dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath][]|Windows `keychain`|macOS Keychain.|macOS -`secretservice`|[freedesktop.org Secret Service API][] via [libsecret][] (requires a graphical interface to unlock secret collections).|Linux -`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility][] (requires GPG and `pass` to initialize the store).|macOS, Linux -`cache`|Git's built-in [credential cache][].|Windows, macOS, Linux +`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][] (requires a graphical interface to unlock secret collections).|Linux +`gpg`|Use GPG to store encrypted files that are compatible with the [pass][] (requires GPG and `pass` to initialize the store).|macOS, Linux +`cache`|Git's built-in [credential cache][credential-cache].|Windows, macOS, Linux `plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`][].|Windows, macOS, Linux #### Example @@ -426,7 +426,7 @@ Use the operating system account manager where available. Defaults to `false`. This default is subject to change in the future. -_**Note:** before you enable this option on Windows, please review the [Windows Broker][] details for what this means to your local Windows user account._ +_**Note:** before you enable this option on Windows, please review the [Windows Broker][wam] details for what this means to your local Windows user account._ Value|Description -|- @@ -445,7 +445,7 @@ git config --global credential.msauthUseBroker true ### credential.useHttpPath -Tells Git to pass the entire repository URL, rather than just the hostname, when calling out to a credential provider. (This setting [comes from Git itself][], not GCM.) +Tells Git to pass the entire repository URL, rather than just the hostname, when calling out to a credential provider. (This setting [comes from Git itself][use-http-path], not GCM.) Defaults to `false`. @@ -519,7 +519,7 @@ Value|Description `pat` _(default)_|Azure DevOps personal access tokens `oauth`|Microsoft identity OAuth tokens (AAD or MSA tokens) -Here is more information about [Azure Access tokens][]. +Here is more information about [Azure Access tokens][azure-tokens]. #### Example @@ -530,18 +530,18 @@ git config --global credential.azreposCredentialType oauth **Also see: [GCM_AZREPOS_CREDENTIALTYPE][]** [auto-detection]: autodetect.md -[Azure Access Tokens]: azrepos-azuretokens.md -[comes from Git itself]: https://git-scm.com/docs/gitcredentials/#Documentation/gitcredentials.txt-useHttpPath +[azure-tokens]: azrepos-azuretokens.md +[use-http-path]: https://git-scm.com/docs/gitcredentials/#Documentation/gitcredentials.txt-useHttpPath [`credential.credentialStore`]: #credentialcredentialstore [credential.dpapiStorePath]: #credentialdpapistorepath [credential.interactive]: #credentialinteractive [`credential.msauthUseBroker`]: #credentialmsauthusebroker-experimental [`credential.plaintextStorePath`]: #credentialplaintextstorepath -[credential cache]: https://git-scm.com/docs/git-credential-cache -[credential stores]: credstores.md -[default values]: enterprise-config.md -[environment variables]: environment.md -[freedesktop.org Secret Service API]: https://specifications.freedesktop.org/secret-service/ +[credential-cache]: https://git-scm.com/docs/git-credential-cache +[cred-stores]: credstores.md +[enterprise-conf]: enterprise-config.md +[envars]: environment.md +[freedesktop-ss]: https://specifications.freedesktop.org/secret-service/ [GCM_ALLOW_WINDOWSAUTH]: environment.md#GCM_ALLOW_WINDOWSAUTH [GCM_AUTHORITY]: environment.md#GCM_AUTHORITY-deprecated [GCM_AUTODETECT_TIMEOUT]: environment.md#GCM_AUTODETECT_TIMEOUT @@ -561,12 +561,12 @@ 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 -[Git Credential Manager]: usage.md +[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 -[learn more]: autodetect.md +[http-proxy]: netconfig.md#http-proxy +[autodetect]: autodetect.md [libsecret]: https://wiki.gnome.org/Projects/Libsecret -[migration guide]: migration.md#gcm_authority -[options]: https://git-scm.com/docs/git-credential-cache#_options -[`pass` utility]: https://www.passwordstore.org/ -[Windows Broker]: windows-broker.md +[provider-migrate]: migration.md#gcm_authority +[cache-options]: https://git-scm.com/docs/git-credential-cache#_options +[pass]: https://www.passwordstore.org/ +[wam]: windows-broker.md