diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a7a7e0e63..46e9cffc1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -73,6 +73,6 @@ available at [Contributor Covenant Code of Conduct][cc-coc]. For answers to common questions about this code of conduct, see the [Contributor Covenant FAQ][cc-faq] -[cc-homepage]: https://www.contributor-covenant.org [cc-coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [cc-faq]: https://www.contributor-covenant.org/faq +[cc-homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e6774c1e..7687714fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,8 @@ # Contributing -[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues -[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork -[pr]: https://github.com/GitCredentialManager/git-credential-manager/compare -[code-of-conduct]: CODE_OF_CONDUCT.md - Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. -Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). +Contributions to this project are [released][contribute-under-repo-license] to the public under the [project's open source license][license]. Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms. @@ -29,7 +24,7 @@ This helps us coordinate and reduce duplication. - `GitHub.UI.Avalonia` - `Atlassian.Bitbucket.UI.Windows` - `GitHub.UI.Windows` -1. Push to your fork and [submit a pull request][pr] +1. Push to your fork and [submit a pull request][compare] 1. Pat your self on the back and wait for your pull request to be reviewed and merged. Here are a few things you can do that will increase the likelihood of your pull request being accepted: @@ -37,10 +32,21 @@ Here are a few things you can do that will increase the likelihood of your pull - Match existing code style. - Write tests. - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. -- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +- Write a [good commit message][commit-messages]. ## Resources -- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) -- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) -- [GitHub Help](https://help.github.com) +- [How to Contribute to Open Source][how-to-contribute] +- [Using Pull Requests][prs] +- [GitHub Help][github-help] + +[code-of-conduct]: CODE_OF_CONDUCT.md +[commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +[compare]: https://github.com/GitCredentialManager/git-credential-manager/compare +[contribute-under-repo-license]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license +[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork +[github-help]: https://help.github.com +[how-to-contribute]: https://opensource.guide/how-to-contribute/ +[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues +[license]: LICENSE +[prs]: https://help.github.com/articles/about-pull-requests/ diff --git a/README.md b/README.md index 7071f57e3..7e7f9f9ae 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,27 @@ # Git Credential Manager -[![Build Status](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml) +[![Build Status][build-status-badge]][workflow-status] --- -[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is a secure Git credential helper built on [.NET](https://dotnet.microsoft.com) that runs on Windows, macOS, and Linux. +[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][] that runs on Windows, macOS, and Linux. -Compared to Git's [built-in credential helpers]((https://git-scm.com/book/en/v2/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](https://dev.azure.com/), Azure DevOps Server (formerly Team Foundation Server), GitHub, Bitbucket, and GitLab. +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. -Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows](https://github.com/microsoft/Git-Credential-Manager-for-Windows) (GCM), and the Java-based [Git Credential Manager for Mac and Linux](https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux) (Java GCM), providing a consistent authentication experience across all platforms. +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. ## Current status 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](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops) -- [GitHub SSH](https://help.github.com/en/articles/connecting-to-github-with-ssh) -- [Bitbucket SSH](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) +- [Azure DevOps SSH][] +- [GitHub SSH][] +- [Bitbucket SSH][] Feature|Windows|macOS|Linux -|:-:|:-:|:-: Installer/uninstaller|✓|✓|✓\* -Secure platform credential storage|✓ [(see more)](docs/credstores.md)|✓ [(see more)](docs/credstores.md)|✓ [(see more)](docs/credstores.md) +Secure platform credential storage|✓ [(see more)][gcm-credstores]|✓ [(see more)][gcm-credstores]|✓ [(see more)][gcm-credstores] Multi-factor authentication support for Azure DevOps|✓|✓|✓ Two-factor authentication support for GitHub|✓|✓|✓ Two-factor authentication support for Bitbucket|✓|✓|✓ @@ -75,7 +75,7 @@ brew uninstall --cask git-credential-manager-core ### macOS Package -We also provide a [.pkg installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) with each release. To install, double-click the installation package and follow the instructions presented. +We also provide a [.pkg installer][latest-release] with each release. To install, double-click the installation package and follow the instructions presented. #### Uninstall @@ -121,7 +121,7 @@ run the following: #### Ubuntu/Debian distributions -Download the latest [.deb package](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following: +Download the latest [.deb package][latest-release], and run the following: ```shell sudo dpkg -i @@ -129,7 +129,7 @@ git-credential-manager-core configure ``` **Note:** Although packages were previously offered on certain -[Microsoft Ubuntu package feeds](https://packages.microsoft.com/repos/), +[Microsoft Ubuntu package feeds][ms-package-repos], GCM no longer publishes to these repositories. Please install the Debian package using the above instructions instead. @@ -142,7 +142,7 @@ sudo dpkg -r gcmcore #### Other distributions -Download the latest [tarball](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following: +Download the latest [tarball][latest-release], and run the following: ```shell tar -xvf -C /usr/local/bin @@ -156,19 +156,19 @@ git-credential-manager-core unconfigure rm $(command -v git-credential-manager-core) ``` -**Note:** all Linux distributions [require additional configuration](https://aka.ms/gcm/credstores) to use GCM. +**Note:** all Linux distributions [require additional configuration][gcm-credstores] to use GCM. --- ### Windows -GCM is included with [Git for Windows](https://gitforwindows.org/), 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][], 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](https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png) +![image][git-for-windows-screenshot] #### Standalone installation -You can also download the [latest installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) for Windows to install GCM standalone. +You can also download the [latest installer][latest-release] for Windows to install GCM standalone. **:warning: Important :warning:** @@ -197,10 +197,10 @@ To uninstall, open Control Panel and navigate to the Programs and Features scree #### Windows Subsystem for Linux (WSL) Git Credential Manager can be used with the [Windows Subsystem for Linux -(WSL)](https://aka.ms/wsl) to enable secure authentication of your remote Git +(WSL)][ms-wsl] to enable secure authentication of your remote Git repositories from inside of WSL. -[Please see the GCM on WSL docs](docs/wsl.md) for more information. +[Please see the GCM on WSL docs][gcm-wsl] for more information. ## Supported Git versions @@ -215,50 +215,89 @@ Git that are not compatible. - Git 2.26.2 This version of Git introduced a breaking change with parsing credential - configuration that GCM relies on. This issue was fixed in commit [`12294990`](https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340) + configuration that GCM relies on. This issue was fixed in commit [`12294990`][gcm-commit-12294990] of the Git project, and released in Git 2.27.0. ## How to use 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](https://dev.azure.com), [Bitbucket](https://bitbucket.org), or [GitHub](https://github.com), a window will automatically open and walk you through the sign-in process. +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. (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. -Read full command line usage [here](docs/usage.md). +Read full command line usage [here][gcm-usage]. ### Configuring a proxy -See detailed information [here](https://aka.ms/gcm/httpproxy). +See detailed information [here][gcm-http-proxy]. ## Additional Resources -- [Frequently asked questions](docs/faq.md) -- [Development and debugging](docs/development.md) -- [Command-line usage](docs/usage.md) -- [Configuration options](docs/configuration.md) -- [Environment variables](docs/environment.md) -- [Enterprise configuration](docs/enterprise-config.md) -- [Network and HTTP configuration](docs/netconfig.md) -- [Credential stores](docs/credstores.md) -- [Architectural overview](docs/architecture.md) -- [Host provider specification](docs/hostprovider.md) -- [Azure Repos OAuth tokens](docs/azrepos-users-and-tokens.md) -- [GitLab support](docs/gitlab.md) +- [Frequently asked questions][gcm-faq] +- [Development and debugging][gcm-dev] +- [Command-line usage][gcm-usage] +- [Configuration options][gcm-config] +- [Environment variables][gcm-env] +- [Enterprise configuration][gcm-enterprise-config] +- [Network and HTTP configuration][gcm-net-config] +- [Credential stores][gcm-credstores] +- [Architectural overview][gcm-arch] +- [Host provider specification][gcm-host-provider] +- [Azure Repos OAuth tokens][gcm-azure-tokens] +- [GitLab support][gcm-gitlab] ## Experimental Features -- [Windows broker (experimental)](docs/windows-broker.md) +- [Windows broker (experimental)][gcm-windows-broker] ## Contributing This project welcomes contributions and suggestions. -See the [contributing guide](CONTRIBUTING.md) to get started. +See the [contributing guide][gcm-contributing] to get started. -This project follows [GitHub's Open Source Code of Conduct](CODE_OF_CONDUCT.md). +This project follows [GitHub's Open Source Code of Conduct][gcm-coc]. ## License -We're [MIT](LICENSE) licensed. -When using GitHub logos, please be sure to follow the [GitHub logo guidelines](https://github.com/logos). +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 +[build-status-badge]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg +[.NET]: 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 +[gcm-coc]: CODE_OF_CONDUCT.md +[gcm-commit-12294990]: https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340 +[gcm-config]: docs/configuration.md +[gcm-contributing]: CONTRIBUTING.md +[gcm-credstores]: docs/credstores.md +[gcm-dev]: docs/development.md +[gcm-enterprise-config]: docs/enterprise-config.md +[gcm-env]: docs/environment.md +[gcm-faq]: docs/faq.md +[gcm-for-mac-and-linux]: https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux +[gcm-for-windows]: https://github.com/microsoft/Git-Credential-Manager-for-Windows +[gcm-gitlab]: docs/gitlab.md +[gcm-host-provider]: docs/hostprovider.md +[gcm-http-proxy]: docs/netconfig.md#http-proxy +[gcm-license]: LICENSE +[gcm-net-config]: docs/netconfig.md +[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-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-logos]: https://github.com/logos +[latest-release]: https://github.com/GitCredentialManager/git-credential-manager/releases/latest +[ms-package-repos]: https://packages.microsoft.com/repos/ +[ms-wsl]: https://aka.ms/wsl# +[workflow-status]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml diff --git a/SECURITY.md b/SECURITY.md index 8785fd5ba..e9a6244a3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security -If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github) +If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty][hackerone-github] Thanks for helping make GitHub products safe for everyone. + +[hackerone-github]: https://hackerone.com/github diff --git a/docs/architecture.md b/docs/architecture.md index eee92e3e3..3828c4c2f 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](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet)) +> `Microsoft.Identity.Client` ([MSAL.NET][]) > library requires a .NET Framework target to be able to show the embedded web > browser auth pop-up on Windows platforms. > @@ -52,8 +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 [this](https://github.com/GitCredentialManager/git-credential-manager/issues/113) -> issue for more information. +> See [GCM 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. @@ -80,9 +79,9 @@ helpers on Windows. ### Cross-platform UI -We hope to be able to migrate the WPF/Windows only helpers to [Avalonia](https://avaloniaui.net/) -in order to gain cross-platform graphical user interface support. See [this](https://github.com/GitCredentialManager/git-credential-manager/issues/136) -issue for up-to-date progress on this effort. +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. ### Microsoft authentication @@ -148,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`](../src/shared/Git-Credential-Manager/Program.cs). +method in [`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, @@ -162,7 +161,7 @@ The `Get|Store|EraseCommand`s consult the host provider registry for the most appropriate host provider. The default registry implementation select the a host provider by asking each registered provider in turn if they understand the request. The provider selection can be overridden by the user via the -[`credential.provider`](configuration.md#credentialprovider) or [`GCM_PROVIDER`](environment.md#GCM_PROVIDER) +[`credential.provider`][] or [`GCM_PROVIDER`][] configuration and environment variable respectively (3)). The `Get|Store|EraseCommand`s call the corresponding @@ -277,3 +276,11 @@ operation/authentication. The `ITrace` component can be found on the `ICommandContext` object or passed in directly to some constructors. Verbose and diagnostic information is be written to the trace object in most places of GCM. + +[avalonia]: https://avaloniaui.net/ +[`core.program`]: ../src/shared/Git-Credential-Manager/Program.cs +[`credential.provider`]: configuration.md#credentialprovider +[GCM issue 113]: https://github.com/GitCredentialManager/git-credential-manager/issues/113 +[GCM issue 136]: https://github.com/GitCredentialManager/git-credential-manager/issues/136 +[`GCM_PROVIDER`]: environment.md#GCM_PROVIDER +[msal.net]: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet diff --git a/docs/autodetect.md b/docs/autodetect.md index 398b7598f..dee8694e8 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](#manual-configuration) +If a heuristic matches incorrectly, you can always [explicitly configure][] GCM to use a particular provider. ## Remote URL probing @@ -28,19 +28,19 @@ 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](#explicit-configuration) +received by Git. To avoid this network call, please [explicitly configure][] the host provider for your self-hosted instance. After a successful detection of the host provider, GCM will automatically set -the [`credential.provider` configuration entry](configuration.md#credentialprovider) +the [`credential.provider`][] configuration entry for that remote to avoid needing to perform this expensive network call in future requests. ### Timeout You can control how long GCM will wait for a response to the remote network call -by setting the [`GCM_AUTODETECT_TIMEOUT`](environment.md#GCM_AUTODETECT_TIMEOUT) -environment variable, or the [`credential.autoDetectTimeout`](configuration.md#credentialautodetecttimeout) +by setting the [`GCM_AUTODETECT_TIMEOUT`][] +environment variable, or the [`credential.autoDetectTimeout`][] Git configuration setting to the maximum number of milliseconds to wait. The default value is 2000 milliseconds (2 seconds). You can prevent the network @@ -52,8 +52,8 @@ If the auto-detection mechanism fails to select the correct host provider, or if the remote probing network call is causing performance issues, you can configure GCM to always use a particular host provider, for a given remote URL. -You can either use the the [`GCM_PROVIDER`](environment.md#GCM_PROVIDER) -environment variable, or the [`credential.provider`](configuration.md#credentialprovider) +You can either use the the [`GCM_PROVIDER`][] +environment variable, or the [`credential.provider`][] Git configuration setting for this purpose. For example to tell GCM to always use the GitHub host provider for the @@ -62,3 +62,9 @@ For example to tell GCM to always use the GitHub host provider for the ```shell git config --global credential.ghe.example.com.provider github ``` + +[`credential.autoDetectTimeout`]: configuration.md#credentialautodetecttimeout +[`credential.provider`]: configuration.md#credentialprovider +[explicitly configure]: #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 1aab32262..d528c6f87 100644 --- a/docs/azrepos-users-and-tokens.md +++ b/docs/azrepos-users-and-tokens.md @@ -8,8 +8,8 @@ The Azure Repos host provider supports creating multiple types of credential: - Microsoft identity OAuth tokens To select which type of credential the Azure Repos host provider will create -and use, you can set the [`credential.azreposCredentialType`](configuration.md#credentialazreposcredentialtype) -configuration entry (or [`GCM_AZREPOS_CREDENTIALTYPE`](environment.md#GCM_AZREPOS_CREDENTIALTYPE) +and use, you can set the [`credential.azreposCredentialType`][] +configuration entry (or [`GCM_AZREPOS_CREDENTIALTYPE`][] environment variable). ### Azure DevOps personal access tokens @@ -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](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) or [REST API](https://docs.microsoft.com/en-gb/rest/api/azure/devops/tokens/pats). +DevOps user settings page][azure-devops-pats] or [REST 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,8 +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](https://tools.ietf.org/html/rfc3986#section-3.2.1) part of -the URL. +[user information][] part of the URL. ```shell git config --local remote.origin.url https://alice-alt%40contoso.com@contoso.visualstudio.com/project/_git/repo @@ -218,3 +217,9 @@ contoso: fabrikam: (global) -> alice@fabrikam.com ``` + +[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 diff --git a/docs/bitbucket-development.md b/docs/bitbucket-development.md index dc7140770..23e3c6e96 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](https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html). +Read about [Bitbucket's 2FA implementation][]. 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](https://confluence.atlassian.com/display/BITBUCKET/App+passwords). +[Additional information][]. 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](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). +Read more about information [Bitbucket's OAuth implementation][]. 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](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx) 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][] 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. @@ -65,7 +65,7 @@ The Access and Refresh Tokens will be stored against the username and the userna ## On-Premise Bitbucket -On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, [bitbucket.org](https://bitbucket.org). +On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, [bitbucket.org][]. As far as GCMC is concerned the main difference it doesn't support OAuth so only Basic Authentication is available. @@ -73,10 +73,18 @@ It is possible to test with Bitbucket Server by running it locally using the fol ❯ atlas-run-standalone --product bitbucket -See the developer documentation for [atlas-run-standalone](https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/). +See the developer documentation for [atlas-run-standalone][]. This will download and run a standalone instance of Bitbucket Server which can be accessed using the credentials `admin`/`admin` at https://localhost:7990/bitbucket -Atlassian has [documentation](https://developer.atlassian.com/server/framework/atlassian-sdk/) on how to download and install their SDK. +Atlassian has [documentation][] on how to download and install their SDK. + +[Additional information]: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 +[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 diff --git a/docs/configuration.md b/docs/configuration.md index 06a46eb5a..585d394f3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration options -[Git Credential Manager](usage.md) works out of the box for most users. +[Git Credential Manager][] 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](environment.md) **which take precedence over configuration options**. System administrators may also configure [default values](enterprise-config.md) for many settings used by GCM. +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. 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. @@ -50,7 +50,7 @@ git config --global credential.interactive false Defaults to enabled. -**Also see: [GCM_INTERACTIVE](environment.md#GCM_INTERACTIVE)** +**Also see: [GCM_INTERACTIVE][]** --- @@ -60,7 +60,7 @@ Define the host provider to use when authenticating. ID|Provider -|- -`auto` _(default)_|_\[automatic\]_ ([learn more](autodetect.md)) +`auto` _(default)_|_\[automatic\]_ ([learn more][]) `azure-repos`|Azure Repos `github`|GitHub `bitbucket`|Bitbucket @@ -77,7 +77,7 @@ This setting is typically used with a scoped URL to map a particular set of remo git config --global credential.ghe.contoso.com.provider github ``` -**Also see: [GCM_PROVIDER](environment.md#GCM_PROVIDER)** +**Also see: [GCM_PROVIDER][]** --- @@ -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. > -> Click [here](https://aka.ms/gcm/authority) for more information. +> See the [migration guide][] for more information. Select the host provider to use when authenticating by which authority is supported by the providers. @@ -104,7 +104,7 @@ Authority|Provider(s) git config --global credential.ghe.contoso.com.authority github ``` -**Also see: [GCM_AUTHORITY](environment.md#GCM_AUTHORITY-deprecated)** +**Also see: [GCM_AUTHORITY][]** --- @@ -113,7 +113,7 @@ git config --global credential.ghe.contoso.com.authority github Permit or disable GCM from presenting GUI prompts. If an equivalent terminal/ text-based prompt is available, that will be shown instead. -To disable all interactivity see [credential.interactive](#credentialinteractive). +To disable all interactivity see [credential.interactive][]. #### Example @@ -123,7 +123,7 @@ git config --global credential.guiPrompt false Defaults to enabled. -**Also see: [GCM_GUI_PROMPT](environment.md#GCM_GUI_PROMPT)** +**Also see: [GCM_GUI_PROMPT][]** --- @@ -132,7 +132,7 @@ Defaults to enabled. Set the maximum length of time, in milliseconds, that GCM should wait for a network response during host provider auto-detection probing. -See [here](autodetect.md) for more information. +See [auto-detection][] for more information. **Note:** Use a negative or zero value to disable probing altogether. @@ -144,7 +144,7 @@ Defaults to 2000 milliseconds (2 seconds). git config --global credential.autoDetectTimeout -1 ``` -**Also see: [GCM_AUTODETECT_TIMEOUT](environment.md#GCM_AUTODETECT_TIMEOUT)** +**Also see: [GCM_AUTODETECT_TIMEOUT][]** --- @@ -167,15 +167,15 @@ Value|WIA detection git config --global credential.tfsonprem123.allowWindowsAuth false ``` -**Also see: [GCM_ALLOW_WINDOWSAUTH](environment.md#GCM_ALLOW_WINDOWSAUTH)** +**Also see: [GCM_ALLOW_WINDOWSAUTH][]** --- ### credential.httpProxy _(deprecated)_ -> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). +> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-config-http-proxy]. > -> Click [here](https://aka.ms/gcm/httpproxy) for more information. +> See [HTTP Proxy][] for more information. Configure GCM to use the a proxy for network operations. @@ -187,7 +187,7 @@ Configure GCM to use the a proxy for network operations. git config --global credential.httpsProxy http://john.doe:password@proxy.contoso.com ``` -**Also see: [GCM_HTTP_PROXY](environment.md#GCM_HTTP_PROXY-deprecated)** +**Also see: [GCM_HTTP_PROXY][]** --- @@ -212,7 +212,7 @@ _(unset)_|Automatically detect modes git config --global credential.bitbucketAuthModes "oauth,basic" ``` -**Also see: [GCM_BITBUCKET_AUTHMODES](environment.md#GCM_BITBUCKET_AUTHMODES)** +**Also see: [GCM_BITBUCKET_AUTHMODES][]** --- @@ -239,7 +239,7 @@ git config --global credential.bitbucketAlwaysRefreshCredentials 1 Defaults to false/disabled. -**Also see: [GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS](environment.md#GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS)** +**Also see: [GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS][]** --- @@ -265,7 +265,7 @@ _(unset)_|Automatically detect modes git config --global credential.gitHubAuthModes "oauth,basic" ``` -**Also see: [GCM_GITHUB_AUTHMODES](environment.md#GCM_GITHUB_AUTHMODES)** +**Also see: [GCM_GITHUB_AUTHMODES][]** --- @@ -289,7 +289,7 @@ _(unset)_|Automatically detect modes git config --global credential.gitLabAuthModes "browser" ``` -**Also see: [GCM_GITLAB_AUTHMODES](environment.md#GCM_GITLAB_AUTHMODES)** +**Also see: [GCM_GITLAB_AUTHMODES][]** --- @@ -306,7 +306,7 @@ Defaults to the value `git`. git config --global credential.namespace "my-namespace" ``` -**Also see: [GCM_NAMESPACE](environment.md#GCM_NAMESPACE)** +**Also see: [GCM_NAMESPACE][]** --- @@ -316,18 +316,18 @@ 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 [here](credstores.md). +**Note:** See more information about configuring secret stores in [credential stores][]. Value|Credential Store|Platforms -|-|- _(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](#credentialdpapistorepath)|Windows +`dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath][]|Windows `keychain`|macOS Keychain.|macOS -`secretservice`|[freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) via [libsecret](https://wiki.gnome.org/Projects/Libsecret) (requires a graphical interface to unlock secret collections).|Linux -`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility](https://www.passwordstore.org/) (requires GPG and `pass` to initialize the store).|macOS, Linux -`cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).|Windows, macOS, Linux -`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`](#credentialplaintextstorepath).|Windows, macOS, Linux +`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 +`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`][].|Windows, macOS, Linux #### Example @@ -335,15 +335,14 @@ _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|- git config --global credential.credentialStore gpg ``` -**Also see: [GCM_CREDENTIAL_STORE](environment.md#GCM_CREDENTIAL_STORE)** +**Also see: [GCM_CREDENTIAL_STORE][]** --- ### credential.cacheOptions -Pass [options](https://git-scm.com/docs/git-credential-cache#_options) -to the Git credential cache when -[`credential.credentialStore`](#credentialcredentialstore) +Pass [options][] to the Git credential cache when +[`credential.credentialStore`][] is set to `cache`. This allows you to select a different amount of time to cache credentials (the default is 900 seconds) by passing `"--timeout "`. Use of other options like `--socket` is untested @@ -357,13 +356,13 @@ Defaults to empty. git config --global credential.cacheOptions "--timeout 300" ``` -**Also see: [GCM_CREDENTIAL_CACHE_OPTIONS](environment.md#GCM_CREDENTIAL_CACHE_OPTIONS)** +**Also see: [GCM_CREDENTIAL_CACHE_OPTIONS][]** --- ### credential.plaintextStorePath -Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `plaintext`. +Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`][] is set to `plaintext`. Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`. @@ -373,13 +372,13 @@ Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`. git config --global credential.plaintextStorePath /mnt/external-drive/credentials ``` -**Also see: [GCM_PLAINTEXT_STORE_PATH](environment.md#GCM_PLAINTEXT_STORE_PATH)** +**Also see: [GCM_PLAINTEXT_STORE_PATH][]** --- ### credential.dpapiStorePath -Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `dpapi`. +Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`][] is set to `dpapi`. Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. @@ -389,7 +388,7 @@ Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. git config --global credential.dpapiStorePath D:\credentials ``` -**Also see: [GCM_DPAPI_STORE_PATH](environment.md#GCM_DPAPI_STORE_PATH)** +**Also see: [GCM_DPAPI_STORE_PATH][]** --- @@ -399,7 +398,7 @@ Specify which authentication flow should be used when performing Microsoft authe Defaults to `auto`. -**Note:** If [`credential.msauthUseBroker`](#credentialmsauthusebroker-experimental) is set +**Note:** If [`credential.msauthUseBroker`][] is set to `true` and the operating system authentication broker is available, all flows will be delegated to the broker. If both of those things are true, then the value of `credential.msauthFlow` has no effect. @@ -417,7 +416,7 @@ Value|Authentication Flow git config --global credential.msauthFlow devicecode ``` -**Also see: [GCM_MSAUTH_FLOW](environment.md#GCM_MSAUTH_FLOW)** +**Also see: [GCM_MSAUTH_FLOW][]** --- @@ -427,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 details](windows-broker.md) about what this means to your local Windows user account._ +_**Note:** before you enable this option on Windows, please review the [Windows Broker][] details for what this means to your local Windows user account._ Value|Description -|- @@ -440,13 +439,13 @@ Value|Description git config --global credential.msauthUseBroker true ``` -**Also see: [GCM_MSAUTH_USEBROKER](environment.md#GCM_MSAUTH_USEBROKER-experimental)** +**Also see: [GCM_MSAUTH_USEBROKER][]** --- ### 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](https://git-scm.com/docs/gitcredentials/#Documentation/gitcredentials.txt-useHttpPath), 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][], not GCM.) Defaults to `false`. @@ -520,7 +519,7 @@ Value|Description `pat` _(default)_|Azure DevOps personal access tokens `oauth`|Microsoft identity OAuth tokens (AAD or MSA tokens) -More information about Azure Access tokens can be found [here](azrepos-azuretokens.md). +Here is more information about [Azure Access tokens][]. #### Example @@ -528,4 +527,46 @@ More information about Azure Access tokens can be found [here](azrepos-azuretoke git config --global credential.azreposCredentialType oauth ``` -**Also see: [GCM_AZREPOS_CREDENTIALTYPE](environment.md#GCM_AZREPOS_CREDENTIALTYPE)** +**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 +[`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/ +[GCM_ALLOW_WINDOWSAUTH]: environment.md#GCM_ALLOW_WINDOWSAUTH +[GCM_AUTHORITY]: environment.md#GCM_AUTHORITY-deprecated +[GCM_AUTODETECT_TIMEOUT]: environment.md#GCM_AUTODETECT_TIMEOUT +[GCM_AZREPOS_CREDENTIALTYPE]: environment.md#GCM_AZREPOS_CREDENTIALTYPE +[GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS]: environment.md#GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS +[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_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 +[GCM_GUI_PROMPT]: environment.md#GCM_GUI_PROMPT +[GCM_HTTP_PROXY]: environment.md#GCM_HTTP_PROXY-deprecated +[GCM_INTERACTIVE]: environment.md#GCM_INTERACTIVE +[GCM_MSAUTH_FLOW]: environment.md#GCM_MSAUTH_FLOW +[GCM_MSAUTH_USEBROKER]: environment.md#GCM_MSAUTH_USEBROKER-experimental +[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 +[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 +[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 diff --git a/docs/credstores.md b/docs/credstores.md index 3e4a232f2..f7d5efb5c 100644 --- a/docs/credstores.md +++ b/docs/credstores.md @@ -5,9 +5,9 @@ There are several options for storing credentials that GCM supports: - Windows Credential Manager - DPAPI protected files - macOS Keychain -- [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) -- GPG/[`pass`](https://www.passwordstore.org/) compatible files -- Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache) +- [freedesktop.org Secret Service API][] +- GPG/[`pass`][] compatible files +- Git's built-in [credential cache][] - Plaintext files The default credential stores on macOS and Windows are the macOS Keychain and @@ -15,8 +15,8 @@ the Windows Credential Manager, respectively. GCM comes without a default store on Linux distributions. -You can select which credential store to use by setting the [`GCM_CREDENTIAL_STORE`](environment.md#GCM_CREDENTIAL_STORE) -environment variable, or the [`credential.credentialStore`](configuration.md#credentialcredentialstore) +You can select which credential store to use by setting the [`GCM_CREDENTIAL_STORE`][] +environment variable, or the [`credential.credentialStore`][] Git configuration setting. For example: ```shell @@ -49,8 +49,7 @@ This credential store uses the Windows Credential APIs (`wincred.h`) to store data securely in the Windows Credential Manager (also known as the Windows Credential Vault in earlier versions of Windows). -You can [access and manage data in the credential manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0) -from the control panel, or via the [`cmdkey` command-line tool](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmdkey). +You can [access and manage data in the credential manager][] from the control panel, or via the [`cmdkey` command-line tool][]. When connecting to a Windows machine over a network session (such as SSH), GCM is unable to persist credentials to the Windows Credential Manager due to @@ -73,7 +72,7 @@ git config --global credential.credentialStore dpapi This credential store uses Windows DPAPI to encrypt credentials which are stored as files in your file system. The file structure is the same as the -[plaintext files credential store](#plaintext-files) except the first line (the +[plaintext files credential store][] except the first line (the secret value) is protected by DPAPI. By default files are stored in `%USERPROFILE%\.gcm\dpapi_store`. This can be @@ -97,10 +96,10 @@ git config --global credential.credentialStore keychain This credential store uses the default macOS Keychain, which is typically the `login` keychain. -You can [manage data stored in the keychain](https://support.apple.com/en-gb/guide/mac-help/mchlf375f392/mac) +You can [manage data stored in the keychain][] using the Keychain Access application. -## [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) +## [freedesktop.org Secret Service API][] **Available on:** _Linux_ @@ -119,7 +118,7 @@ tools such as `secret-tool` and `seahorse`. A graphical user interface is required in order to show a secure prompt to request a secret collection be unlocked. -## GPG/[`pass`](https://www.passwordstore.org/) compatible files +## GPG/[`pass`][] compatible files **Available on:** _macOS, Linux_ @@ -133,7 +132,7 @@ git config --global credential.credentialStore gpg This credential store uses GPG to encrypt files containing credentials which are stored in your file system. The file structure is compatible with the popular -[`pass`](https://www.passwordstore.org/) tool. By default files are stored in +[`pass`][] tool. By default files are stored in `~/.password-store` but this can be configured using the `pass` environment variable `PASSWORD_STORE_DIR`. @@ -176,7 +175,7 @@ export GPG_TTY=$(tty) **Note:** Using `/dev/tty` does not appear to work here - you must use the real TTY device path, as returned by the `tty` utility. -## Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache) +## Git's built-in [credential cache][] **Available on:** _Windows, macOS, Linux_ @@ -187,17 +186,16 @@ git config --global credential.credentialStore cache ``` This credential store uses Git's built-in ephemeral -[in-memory credential cache](https://git-scm.com/docs/git-credential-cache). +in-memory [credential cache][]. This helps you reduce the number of times you have to authenticate but doesn't require storing credentials on persistent storage. It's good for -scenarios like [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview) -or [AWS CloudShell](https://aws.amazon.com/cloudshell/), where you don't want to +scenarios like [Azure Cloud Shell][] +or [AWS CloudShell][], where you don't want to leave credentials on disk but also don't want to re-authenticate on every Git operation. By default, `git credential-cache` stores your credentials for 900 seconds. -That, and any other -[options it accepts](https://git-scm.com/docs/git-credential-cache#_options), +That, and any other [options it accepts][], may be altered by setting them in the environment variable `GCM_CREDENTIAL_CACHE_OPTIONS` or the Git config value `credential.cacheOptions`. (Using the `--socket` option is untested @@ -232,7 +230,7 @@ On POSIX platforms the newly created store directory will have permissions set such that only the owner can `r`ead/`w`rite/e`x`ecute (`700` or `drwx---`). Permissions on existing directories will not be modified. -NB. GCM's plaintext store is distinct from [git-credential-store](https://git-scm.com/docs/git-credential-store), though the formats are similar. The default paths differ. +NB. GCM's plaintext store is distinct from [git-credential-store][], though the formats are similar. The default paths differ. --- @@ -252,3 +250,17 @@ access files within. If possible, use a path that exists on an external volume that you take with you and use full-disk encryption. --- + +[access and manage data in the credential manager]: https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0 +[AWS CloudShell]: https://aws.amazon.com/cloudshell/ +[Azure Cloud Shell]: https://docs.microsoft.com/azure/cloud-shell/overview +[`cmdkey` command-line tool]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmdkey +[`credential.credentialStore`]: configuration.md#credentialcredentialstore +[credential cache]: https://git-scm.com/docs/git-credential-cache +[freedesktop.org Secret Service API]: https://specifications.freedesktop.org/secret-service/ +[`GCM_CREDENTIAL_STORE`]: environment.md#GCM_CREDENTIAL_STORE +[git-credential-store]: https://git-scm.com/docs/git-credential-store +[manage data stored in the keychain]: https://support.apple.com/en-gb/guide/mac-help/mchlf375f392/mac +[options it accepts]: https://git-scm.com/docs/git-credential-cache#_options +[`pass`]: https://www.passwordstore.org/ +[plaintext files credential store]: #plaintext-files diff --git a/docs/development.md b/docs/development.md index fdec0d8b7..5ee58f73b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,7 +6,7 @@ Start by cloning this repository: git clone https://github.com/GitCredentialManager/git-credential-manager ``` -You also need the latest version of the .NET SDK which can be downloaded and installed from [here](https://dotnet.microsoft.com/). +You also need the latest version of the .NET SDK which can be downloaded and installed from the [.NET website][]. ## Building @@ -58,7 +58,7 @@ The flat binaries can also be found in `out/linux/Packaging.Linux/payload/Debug` To debug from inside an IDE you'll want to set `Git-Credential-Manager` as the startup project, and specify one of `get`, `store`, or `erase` as a program argument. -To simulate Git interacting with GCM, when you start from your IDE of choice, you'll need to enter the following [information over standard input](https://git-scm.com/docs/git-credential#IOFMT): +To simulate Git interacting with GCM, when you start from your IDE of choice, you'll need to enter the following [information over standard input][]: ```text protocol=http @@ -76,7 +76,7 @@ username= password= ``` -For more information about how Git interacts with credential helpers, please read Git's [documentation](https://git-scm.com/docs/gitcredentials#_custom_helpers). +For more information about how Git interacts with credential helpers, please read Git's documentation on [custom helpers][]. ### Attaching to a running process @@ -133,3 +133,7 @@ or ```console report coverage - win ``` + +[.NET website]: https://dotnet.microsoft.com/ +[custom helpers]: https://git-scm.com/docs/gitcredentials#_custom_helpers +[information over standard input]: https://git-scm.com/docs/git-credential#IOFMT diff --git a/docs/enterprise-config.md b/docs/enterprise-config.md index 96ce891d5..1c8e63047 100644 --- a/docs/enterprise-config.md +++ b/docs/enterprise-config.md @@ -3,8 +3,8 @@ Git Credential Manager (GCM) can be configured using multiple different mechanisms. In order of preference, those mechanisms are: -1. [Environment variables](environment.md) -1. [Standard Git configuration files](configuration.md) +1. [Environment variables][] +1. Standard [Git configuration][] files 1. Repository/local configuration (`.git/config`) 1. User/global configuration (`$HOME/.gitconfig` or `%HOME%\.gitconfig`) 1. Installation/system configuration (`etc/gitconfig`) @@ -50,7 +50,7 @@ By using the Windows Registry, system administrators can use Group Policy to easily set defaults for GCM's settings. The names and possible values of all settings under this key are the same as -those of the [Git configuration](configuration.md) settings. +those of the [Git configuration][] settings. The type of each registry key can be either `REG_SZ` (string) or `REG_DWORD` (integer). @@ -58,3 +58,6 @@ The type of each registry key can be either `REG_SZ` (string) or `REG_DWORD` ## macOS/Linux Default configuration setting stores has not been implemented. + +[Environment variables]: environment.md +[Git configuration]: configuration.md