diff --git a/.github/workflows/lint-docs.yml b/.github/workflows/lint-docs.yml new file mode 100644 index 000000000..665e041e2 --- /dev/null +++ b/.github/workflows/lint-docs.yml @@ -0,0 +1,19 @@ +name: "Lint documentation" + +on: + workflow_dispatch: + push: + branches: [ main, linux ] + pull_request: + branches: [ main, linux ] + +jobs: + lint-markdown: + name: Lint markdown files + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@dcd71f646680f2efd8db4afa5ad64fdcba30e748 + + - uses: DavidAnson/markdownlint-cli2-action@744f913a124058ee903768d3adb92a4847e5d132 + with: + globs: "**/*.md" diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 000000000..6e0ac4ada --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,6 @@ +// For information on writing markdownlint configuration see: +// https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig +{ + "MD013": false, // Line length and line breaking convention not yet standardised across docs + "MD024": false // The format for some files require repeated headings, e.g. "Example" +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 3a64696bc..a7a7e0e63 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -67,10 +67,12 @@ members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +This Code of Conduct is adapted from the [Contributor Covenant][cc-homepage], version 1.4, +available at [Contributor Covenant Code of Conduct][cc-coc]. -[homepage]: https://www.contributor-covenant.org +For answers to common questions about this code of conduct, see the +[Contributor Covenant FAQ][cc-faq] -For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff2f5b2ee..9e6774c1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -## Contributing +# Contributing -[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues +[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 @@ -13,24 +13,24 @@ Please note that this project is released with a [Contributor Code of Conduct][c ## Start with an issue -0. Open an [issue][issue] to discuss the change you want to see. +1. Open an [issue][issue] to discuss the change you want to see. This helps us coordinate and reduce duplication. -0. Once we've had some discussion, you're ready to code! +1. Once we've had some discussion, you're ready to code! ## Submitting a pull request -0. [Fork][fork] and clone the repository -0. Configure and install the dependencies: `dotnet restore` -0. Make sure the tests pass on your machine: `dotnet test` -0. Create a new branch: `git switch -c my-branch-name` -0. Make your change, add tests, and make sure the tests still pass -0. For UI updates, test your changes by executing a `dotnet run` in applicable UI-related project directories: +1. [Fork][fork] and clone the repository +1. Configure and install the dependencies: `dotnet restore` +1. Make sure the tests pass on your machine: `dotnet test` +1. Create a new branch: `git switch -c my-branch-name` +1. Make your change, add tests, and make sure the tests still pass +1. For UI updates, test your changes by executing a `dotnet run` in applicable UI-related project directories: - `Atlassian.Bitbucket.UI.Avalonia` - `GitHub.UI.Avalonia` - `Atlassian.Bitbucket.UI.Windows` - `GitHub.UI.Windows` -0. Push to your fork and [submit a pull request][pr] -0. Pat your self on the back and wait for your pull request to be reviewed and merged. +1. Push to your fork and [submit a pull request][pr] +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: diff --git a/README.md b/README.md index b24f31ae1..7071f57e3 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,8 @@ Git Credential Manager is currently available for Windows, macOS, and Linux\*. G 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) +Installer/uninstaller|✓|✓|✓\* +Secure platform credential storage|✓ [(see more)](docs/credstores.md)|✓ [(see more)](docs/credstores.md)|✓ [(see more)](docs/credstores.md) Multi-factor authentication support for Azure DevOps|✓|✓|✓ Two-factor authentication support for GitHub|✓|✓|✓ Two-factor authentication support for Bitbucket|✓|✓|✓ @@ -39,6 +39,7 @@ Proxy support|✓|✓|✓ - Debian/Ubuntu/Linux Mint - Fedora/CentOS/RHEL - Alpine + ## Download and Install ### macOS Homebrew @@ -87,7 +88,9 @@ sudo /usr/local/share/gcm-core/uninstall.sh --- + + ### Linux #### Experimental: install from source helper script @@ -97,24 +100,24 @@ run the following: 1. To ensure `curl` is installed: -```shell -curl --version -``` + ```shell + curl --version + ``` -If `curl` is not installed, please use your distribution's package manager -to install it. + If `curl` is not installed, please use your distribution's package manager + to install it. -0. To download and run the script: +1. To download and run the script: -```shell -curl -LO https://raw.githubusercontent.com/GitCredentialManager/git-credential-manager/main/src/linux/Packaging.Linux/install-from-source.sh && -sh ./install-from-source.sh && -git-credential-manager-core configure -``` + ```shell + curl -LO https://raw.githubusercontent.com/GitCredentialManager/git-credential-manager/main/src/linux/Packaging.Linux/install-from-source.sh && + sh ./install-from-source.sh && + git-credential-manager-core configure + ``` -__Note:__ You will be prompted to enter your credentials so that the script -can download GCM's dependencies using your distribution's package -manager. + **Note:** You will be prompted to enter your credentials so that the script + can download GCM's dependencies using your distribution's package + manager. #### Ubuntu/Debian distributions @@ -124,7 +127,8 @@ Download the latest [.deb package](https://github.com/GitCredentialManager/git-c sudo dpkg -i git-credential-manager-core configure ``` -__Note:__ Although packages were previously offered on certain + +**Note:** Although packages were previously offered on certain [Microsoft Ubuntu package feeds](https://packages.microsoft.com/repos/), GCM no longer publishes to these repositories. Please install the Debian package using the above instructions instead. @@ -249,7 +253,7 @@ See detailed information [here](https://aka.ms/gcm/httpproxy). ## Contributing -This project welcomes contributions and suggestions. +This project welcomes contributions and suggestions. See the [contributing guide](CONTRIBUTING.md) to get started. This project follows [GitHub's Open Source Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/SECURITY.md b/SECURITY.md index 5b2208269..8785fd5ba 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,5 @@ +# Security + If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github) Thanks for helping make GitHub products safe for everyone. diff --git a/docs/azrepos-users-and-tokens.md b/docs/azrepos-users-and-tokens.md index cc26598bb..1aab32262 100644 --- a/docs/azrepos-users-and-tokens.md +++ b/docs/azrepos-users-and-tokens.md @@ -64,7 +64,7 @@ credential. This may change in the future. Normally you won't need to worry about managing which user accounts Git Credential Manager is using as this is configured automatically when you first -authenticate for a particular Azure DevOps organziation. +authenticate for a particular Azure DevOps organization. In advanced scenarios (such as using multiple accounts) you can interact with and manage remembered user accounts using the 'azure-repos' provider command: @@ -181,7 +181,7 @@ fabrikam: ``` In the above example, the `~/myrepo` repository has a single Git remote named -`origin` that points to the `contoso` Azure DevOps organziation. There is no +`origin` that points to the `contoso` Azure DevOps organization. There is no user account specifically associated with the `origin` remote, so the global user account binding for `contoso` will be used (the global binding is inherited). diff --git a/docs/bitbucket-development.md b/docs/bitbucket-development.md index 26dddda90..dc7140770 100644 --- a/docs/bitbucket-development.md +++ b/docs/bitbucket-development.md @@ -63,20 +63,20 @@ Assuming the user successfully logins into Bitbucket and authorizes the GCM this The Access and Refresh Tokens will be stored against the username and the username/Access Token credentials returned to Git. -# On-Premise Bitbucket +## 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, 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](https://bitbucket.org). As far as GCMC is concerned the main difference it doesn't support OAuth so only Basic Authentication is available. It is possible to test with Bitbucket Server by running it locally using the following command from the Atlassian SDK: - ❯ atlas-run-standalone --product bitbucket + ❯ atlas-run-standalone --product bitbucket -See https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/. +See the developer documentation for [atlas-run-standalone](https://developer.atlassian.com/server/framework/atlassian-sdk/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 + https://localhost:7990/bitbucket -Instructions on how to download and install the Atlassian SDK can be found here: https://developer.atlassian.com/server/framework/atlassian-sdk/ +Atlassian has [documentation](https://developer.atlassian.com/server/framework/atlassian-sdk/) on how to download and install their SDK. diff --git a/docs/configuration.md b/docs/configuration.md index e7a7e1cd2..06a46eb5a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -39,8 +39,8 @@ The following table summarizes the change in behavior and the mapping of older v Value(s)|Old meaning|New meaning -|-|- `auto`|Prompt if required – use cached credentials if possible|_(unchanged)_ -`never`,
`false`| Never prompt – fail if interaction is required|_(unchanged)_ -`always`,
`force`,
`true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value) +`never`, `false`| Never prompt – fail if interaction is required|_(unchanged)_ +`always`, `force`, `true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value) #### Example @@ -64,7 +64,7 @@ ID|Provider `azure-repos`|Azure Repos `github`|GitHub `bitbucket`|Bitbucket -`gitlab`|GitLab
_(supports OAuth in browser, personal access token and Basic Authentication)_ +`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_ `generic`|Generic (any other provider not listed above) Automatic provider selection is based on the remote URL. @@ -92,11 +92,11 @@ Select the host provider to use when authenticating by which authority is suppor Authority|Provider(s) -|- `auto` _(default)_|_\[automatic\]_ -`msa`, `microsoft`, `microsoftaccount`,
`aad`, `azure`, `azuredirectory`,
`live`, `liveconnect`, `liveid`|Azure Repos
_(supports Microsoft Authentication)_ -`github`|GitHub
_(supports GitHub Authentication)_ -`bitbucket`|Bitbucket.org
_(supports Basic Authentication and OAuth)_
Bitbucket Server
_(supports Basic Authentication)_ -`gitlab`|GitLab
_(supports OAuth in browser, personal access token and Basic Authentication)_ -`basic`, `integrated`, `windows`, `kerberos`, `ntlm`,
`tfs`, `sso`|Generic
_(supports Basic and Windows Integrated Authentication)_ +`msa`, `microsoft`, `microsoftaccount`, `aad`, `azure`, `azuredirectory`, `live`, `liveconnect`, `liveid`|Azure Repos _(supports Microsoft Authentication)_ +`github`|GitHub _(supports GitHub Authentication)_ +`bitbucket`|Bitbucket.org _(supports Basic Authentication and OAuth)_, Bitbucket Server _(supports Basic Authentication)_ +`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_ +`basic`, `integrated`, `windows`, `kerberos`, `ntlm`, `tfs`, `sso`|Generic _(supports Basic and Windows Integrated Authentication)_ #### Example @@ -196,7 +196,6 @@ git config --global credential.httpsProxy http://john.doe:password@proxy.contoso Override the available authentication modes presented during Bitbucket authentication. If this option is not set, then the available authentication modes will be automatically detected. - **Note:** This setting only applies to Bitbucket.org, and not Server or DC instances. **Note:** This setting supports multiple values separated by commas. @@ -227,7 +226,6 @@ Enabling this option will improve performance when using Oauth2 and interacting Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials everytime. - Value|Refresh Credentials Before Returning -|- `true`, `1`, `yes`, `on` |Always @@ -295,7 +293,6 @@ git config --global credential.gitLabAuthModes "browser" --- - ### credential.namespace Use a custom namespace prefix for credentials read and written in the OS credential store. @@ -323,7 +320,7 @@ Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset o Value|Credential Store|Platforms -|-|- -_(unset)_|Windows: `wincredman`
macOS: `keychain`
Linux: _(none)_|- +_(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 `keychain`|macOS Keychain.|macOS @@ -332,7 +329,7 @@ _(unset)_|Windows: `wincredman`
macOS: `keychain`
Linux: _(none)_|- `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 -##### Example +#### Example ```bash git config --global credential.credentialStore gpg @@ -475,6 +472,7 @@ Credential: "git:https://github.com" (user = alice) https://github.com/contoso/widgets https://alice@github.com/contoso/widgets ``` + ```text Credential: "git:https://bob@github.com" (user = bob) @@ -489,17 +487,20 @@ Credential: "git:https://github.com/foo/bar" (user = alice) https://github.com/foo/bar ``` + ```text Credential: "git:https://github.com/contoso/widgets" (user = alice) https://github.com/contoso/widgets https://alice@github.com/contoso/widgets ``` + ```text Credential: "git:https://bob@github.com/foo/bar" (user = bob) https://bob@github.com/foo/bar ``` + ```text Credential: "git:https://bob@github.com/example/myrepo" (user = bob) diff --git a/docs/development.md b/docs/development.md index 0e8f2dc41..fdec0d8b7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -101,34 +101,35 @@ $ GCM_TRACE=1 git-credential-manager-core version If you want code coverage metrics these can be generated either from the command line: ```shell -$ dotnet test --collect:"XPlat Code Coverage" --settings=./.code-coverage/coverlet.settings.xml +dotnet test --collect:"XPlat Code Coverage" --settings=./.code-coverage/coverlet.settings.xml ``` Or via the VSCode Terminal/Run Task: -``` +```console test with coverage ``` HTML reports can be generated using ReportGenerator, this should be installed during the build process, from the command line: ```shell -$ dotnet ~/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage +dotnet ~/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage ``` + or ```shell -$ dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage +dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage ``` Or via VSCode Terminal/Run Task: -``` +```console report coverage - nix ``` or -``` +```console report coverage - win -``` \ No newline at end of file +``` diff --git a/docs/enterprise-config.md b/docs/enterprise-config.md index 754d0766d..96ce891d5 100644 --- a/docs/enterprise-config.md +++ b/docs/enterprise-config.md @@ -4,12 +4,12 @@ Git Credential Manager (GCM) can be configured using multiple different mechanisms. In order of preference, those mechanisms are: 1. [Environment variables](environment.md) -2. [Standard Git configuration files](configuration.md) +1. [Standard Git configuration files](configuration.md) 1. Repository/local configuration (`.git/config`) - 2. User/global configuration (`$HOME/.gitconfig` or `%HOME%\.gitconfig`) - 3. Installation/system configuration (`etc/gitconfig`) -3. Enterprise system administrator defaults -4. Compiled default values + 1. User/global configuration (`$HOME/.gitconfig` or `%HOME%\.gitconfig`) + 1. Installation/system configuration (`etc/gitconfig`) +1. Enterprise system administrator defaults +1. Compiled default values This model largely matches what Git itself supports, namely environment variables that take precedence over Git configuration files. @@ -18,25 +18,25 @@ The addition of the enterprise system administrator defaults enables those administrators to configure many GCM settings using familiar MDM tooling, rather than having to modify the Git installation configuration files. -### User Freedom +## User Freedom We believe the user should _always_ be at liberty to configure -Git and GCM exactly as they wish. By prefering environment variables and Git +Git and GCM exactly as they wish. By preferring environment variables and Git configuration files over system admin values, these only act as _default values_ -that can always be overriden by the user in the usual ways. +that can always be overridden by the user in the usual ways. ## Windows Default setting values come from the Windows Registry, specifically the following keys: -**32-bit Windows** +### 32-bit Windows ```text HKEY_LOCAL_MACHINE\SOFTWARE\GitCredentialManager\Configuration ``` -**64-bit Windows** +### 64-bit Windows ```text HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\GitCredentialManager\Configuration @@ -55,7 +55,6 @@ those of the [Git configuration](configuration.md) settings. The type of each registry key can be either `REG_SZ` (string) or `REG_DWORD` (integer). - ## macOS/Linux Default configuration setting stores has not been implemented. diff --git a/docs/environment.md b/docs/environment.md index 9237cca94..1089c071a 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -137,8 +137,8 @@ The following table summarizes the change in behavior and the mapping of older v Value(s)|Old meaning|New meaning -|-|- `auto`|Prompt if required – use cached credentials if possible|_(unchanged)_ -`never`,
`false`| Never prompt – fail if interaction is required|_(unchanged)_ -`always`,
`force`,
`true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value) +`never`, `false`| Never prompt – fail if interaction is required|_(unchanged)_ +`always`, `force`, `true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value) #### Example @@ -169,7 +169,7 @@ ID|Provider `auto` _(default)_|_\[automatic\]_ ([learn more](autodetect.md)) `azure-repos`|Azure Repos `github`|GitHub -`gitlab`|GitLab
_(supports OAuth in browser, personal access token and Basic Authentication)_ +`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_ `generic`|Generic (any other provider not listed above) Automatic provider selection is based on the remote URL. @@ -205,10 +205,10 @@ Select the host provider to use when authenticating by which authority is suppor Authority|Provider(s) -|- `auto` _(default)_|_\[automatic\]_ -`msa`, `microsoft`, `microsoftaccount`,
`aad`, `azure`, `azuredirectory`,
`live`, `liveconnect`, `liveid`|Azure Repos
_(supports Microsoft Authentication)_ -`github`|GitHub
_(supports GitHub Authentication)_ -`gitlab`|GitLab
_(supports OAuth in browser, personal access token and Basic Authentication)_ -`basic`, `integrated`, `windows`, `kerberos`, `ntlm`,
`tfs`, `sso`|Generic
_(supports Basic and Windows Integrated Authentication)_ +`msa`, `microsoft`, `microsoftaccount`, `aad`, `azure`, `azuredirectory`, `live`, `liveconnect`, `liveid`|Azure Repos _(supports Microsoft Authentication)_ +`github`|GitHub _(supports GitHub Authentication)_ +`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_ +`basic`, `integrated`, `windows`, `kerberos`, `ntlm`, `tfs`, `sso`|Generic _(supports Basic and Windows Integrated Authentication)_ #### Example @@ -325,13 +325,13 @@ Configure GCM to use the a proxy for network operations. **Note:** Git itself does _not_ respect this setting; this affects GCM _only_. -##### Windows +#### Windows ```batch SET GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.com ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.com @@ -356,13 +356,13 @@ _(unset)_|Automatically detect modes `oauth`|OAuth-based authentication `basic`|Basic/PAT-based authentication -##### Windows +#### Windows ```batch SET GCM_BITBUCKET_AUTHMODES="oauth,basic" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_BITBUCKET_AUTHMODES="oauth,basic" @@ -380,21 +380,20 @@ This is especially relevant to OAuth credentials. Bitbucket.org access tokens ex Enabling this option will improve performance when using Oauth2 and interacting with Bitbucket.org if, on average, commits are done less frequently than every 2 hours. -Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials everytime. - +Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials every time. Value|Refresh Credentials Before Returning -|- `true`, `1`, `yes`, `on` |Always `false`, `0`, `no`, `off`_(default)_|Only when the credentials are found to be invalid -##### Windows +#### Windows ```batch SET GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1 ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1 @@ -422,13 +421,13 @@ _(unset)_|Automatically detect modes `basic`|Basic authentication using username and password `pat`|Personal Access Token (pat)-based authentication -##### Windows +#### Windows ```batch SET GCM_GITHUB_AUTHMODES="oauth,basic" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_GITHUB_AUTHMODES="oauth,basic" @@ -452,13 +451,13 @@ _(unset)_|Automatically detect modes `basic`|Basic authentication using username and password `pat`|Personal Access Token (pat)-based authentication -##### Windows +#### Windows ```batch SET GCM_GITLAB_AUTHMODES="browser" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_GITLAB_AUTHMODES="browser" @@ -475,13 +474,13 @@ Credentials will be stored in the format `{namespace}:{service}`. Defaults to the value `git`. -##### Windows +#### Windows ```batch SET GCM_NAMESPACE="my-namespace" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_NAMESPACE="my-namespace" @@ -501,7 +500,7 @@ Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset o Value|Credential Store|Platforms -|-|- -_(unset)_|Windows: `wincredman`
macOS: `keychain`
Linux: _(none)_|- +_(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 [`GCM_DPAPI_STORE_PATH`](#gcm_dpapi_store_path)|Windows `keychain`|macOS Keychain.|macOS @@ -510,13 +509,13 @@ _(unset)_|Windows: `wincredman`
macOS: `keychain`
Linux: _(none)_|- `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 [`GCM_PLAINTEXT_STORE_PATH`](#gcm_plaintext_store_path).|Windows, macOS, Linux -##### Windows +#### Windows ```batch SET GCM_CREDENTIAL_STORE="gpg" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_CREDENTIAL_STORE="gpg" @@ -597,7 +596,7 @@ Specify the path (_including_ the executable name) to the version of `gpg` used If not specified, GCM defaults to using the version of `gpg2` on the `$PATH`, falling back on `gpg` if `gpg2` is not found. -##### macOS/Linux +#### macOS/Linux ```bash export GCM_GPG_PATH="/usr/local/bin/gpg2" @@ -625,13 +624,13 @@ Value|Authentication Flow `system`|Open the user's default web browser. `devicecode`|Show a device code. -##### Windows +#### Windows ```batch SET GCM_MSAUTH_FLOW="devicecode" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_MSAUTH_FLOW="devicecode" @@ -654,13 +653,13 @@ Value|Description `true`|Use the operating system account manager as an authentication broker. `false` _(default)_|Do not use the broker. -##### Windows +#### Windows ```batch SET GCM_MSAUTH_USEBROKER="true" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_MSAUTH_USEBROKER="false" @@ -683,13 +682,13 @@ Value|Description More information about Azure Access tokens can be found [here](azrepos-azuretokens.md). -##### Windows +#### Windows ```batch SET GCM_AZREPOS_CREDENTIALTYPE="oauth" ``` -##### macOS/Linux +#### macOS/Linux ```bash export GCM_AZREPOS_CREDENTIALTYPE="oauth" diff --git a/docs/faq.md b/docs/faq.md index d95365cf9..130850344 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,17 +14,17 @@ Please follow these steps to diagnose or resolve the problem: 1. If all else fails, create an issue [here](https://github.com/GitCredentialManager/git-credential-manager/issues/create), making sure to include the trace log. -### Q: I got an error saying unsecure HTTP is not supported. +### Q: I got an error saying unsecure HTTP is not supported To keep your data secure, Git Credential Manager will not send credentials for Azure Repos, Azure DevOps Server (TFS), GitHub, and Bitbucket, over HTTP connections that are not secured using TLS (HTTPS). Please make sure your remote URLs use "https://" rather than "http://". -### Q: I got an authentication error and I am behind a network proxy. +### Q: I got an authentication error and I am behind a network proxy You probably need to configure Git and GCM to use a proxy. Please see detailed information [here](https://aka.ms/gcm/httpproxy). -### Q: I'm getting errors about picking a credential store on Linux. +### Q: I'm getting errors about picking a credential store on Linux On Linux you must [select and configure a credential store](https://aka.ms/gcm/credstores), as due to the varied nature of distributions and installations, we cannot guarantee a suitable storage solution is available. @@ -65,7 +65,7 @@ GCM Windows was not designed with a cross-platform architecture. ### What level of support does GCM have? -Support will be best-effort. We would really appreciate your feedback to make this a great experience across each platform we support. +Support will be best-effort. We would really appreciate your feedback to make this a great experience across each platform we support. ### Q: Why does GCM not support operating system/distribution 'X', or Git hosting provider 'Y'? diff --git a/docs/github-apideprecation.md b/docs/github-apideprecation.md index a9c010714..9d5c3b9a3 100644 --- a/docs/github-apideprecation.md +++ b/docs/github-apideprecation.md @@ -53,42 +53,42 @@ GCM for Windows bundled with the Git for Windows installation. If you are unable to use Git Credential Manager due to a bug or compatibility issue we'd [like to know why](https://github.com/GitCredentialManager/git-credential-manager/issues/new/choose)! -## Help! I cannot make any changes to my Windows machine without an Administrator! +## Help! I cannot make any changes to my Windows machine without an Administrator If you do not have permission to change your installation (for example in a corporate environment) you can use the per-user installer. Check out the [latest release](https://aka.ms/gcm/latest) and download the `gcmcoreuser-win-*.exe` executable. -### Help! I still cannot or don't want to install anything! +### Help! I still cannot or don't want to install anything There is a workaround which should work and doesn't require installing anything. 1. Tell your system administrator they should start planning to upgrade the installed version of Git for Windows to at least 2.29! 😁 -2. [Create a new personal access token](https://github.com/settings/tokens/new?scopes=repo,gist,workflow) (see official [documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)) +1. [Create a new personal access token](https://github.com/settings/tokens/new?scopes=repo,gist,workflow) (see official [documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)) -3. Enter a name ("note") for the token and ensure the `repo`, `gist`, and +1. Enter a name ("note") for the token and ensure the `repo`, `gist`, and `workflow` scopes are selected: -![image](https://user-images.githubusercontent.com/5658207/95448332-1beb2000-095b-11eb-9a48-9c05b1926a6b.png) -... -![image](https://user-images.githubusercontent.com/5658207/95447304-6f5c6e80-0959-11eb-924b-50b86c2b3d77.png) -... -![image](https://user-images.githubusercontent.com/5658207/95447450-a3d02a80-0959-11eb-82a8-2d2834d5aa16.png) -... -![image](https://user-images.githubusercontent.com/5658207/95447343-7b483080-0959-11eb-8e00-151d53893f3f.png) + ![image](https://user-images.githubusercontent.com/5658207/95448332-1beb2000-095b-11eb-9a48-9c05b1926a6b.png) + ... + ![image](https://user-images.githubusercontent.com/5658207/95447304-6f5c6e80-0959-11eb-924b-50b86c2b3d77.png) + ... + ![image](https://user-images.githubusercontent.com/5658207/95447450-a3d02a80-0959-11eb-82a8-2d2834d5aa16.png) + ... + ![image](https://user-images.githubusercontent.com/5658207/95447343-7b483080-0959-11eb-8e00-151d53893f3f.png) -3. Click "Generate Token" +1. Click "Generate Token" -![image](https://user-images.githubusercontent.com/5658207/95448393-31f8e080-095b-11eb-9568-cfd1c567a65c.png) + ![image](https://user-images.githubusercontent.com/5658207/95448393-31f8e080-095b-11eb-9568-cfd1c567a65c.png) -4. **[IMPORTANT]** Keep the resulting page open as this contains your new token +1. **[IMPORTANT]** Keep the resulting page open as this contains your new token (this will only be displayed once!) -![image](https://user-images.githubusercontent.com/5658207/95448288-ff4ee800-095a-11eb-9709-8e37bde8b716.png) + ![image](https://user-images.githubusercontent.com/5658207/95448288-ff4ee800-095a-11eb-9709-8e37bde8b716.png) -5. Save the generated PAT in the Windows Credential Manager: +1. Save the generated PAT in the Windows Credential Manager: 1. If you prefer to use the command-line, open a command prompt (cmd.exe) and type the following: @@ -98,7 +98,7 @@ There is a workaround which should work and doesn't require installing anything. ``` You will be prompted to enter a password – copy the newly generated PAT in - step 4 and paste it here, and press Enter + step 4 and paste it here, and press the `Enter` key ![image](https://user-images.githubusercontent.com/5658207/95448479-4fc64580-095b-11eb-9970-0b6faf7f4ae7.png) diff --git a/docs/gitlab.md b/docs/gitlab.md index fd923cb02..0d876d514 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -7,15 +7,15 @@ Git Credential Manager supports [gitlab.com](https://gitlab.com) out the box. To use on another instance, eg. `https://gitlab.example.com` requires setup and configuration: 1. [Create an OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html). This can be at the user, group or instance level. Specify a name and use a redirect URI of `http://127.0.0.1/`. _Unselect_ the 'Confidential' option, and ensure the 'Expire access tokens' option is selected. Set the scope to 'write_repository'. -2. Copy the application ID and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientId ` -3. Copy the application secret and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientSecret ` -4. Configure authentication modes to include 'browser' `git config --global credential.https://gitlab.example.com.gitLabAuthModes browser` -5. For good measure, configure `git config --global credential.https://gitlab.example.com.provider gitlab`. This may be necessary to recognise the domain as a GitLab instance. -6. Verify the config is as expected `git config --global --get-urlmatch credential https://gitlab.example.com` +1. Copy the application ID and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientId ` +1. Copy the application secret and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientSecret ` +1. Configure authentication modes to include 'browser' `git config --global credential.https://gitlab.example.com.gitLabAuthModes browser` +1. For good measure, configure `git config --global credential.https://gitlab.example.com.provider gitlab`. This may be necessary to recognise the domain as a GitLab instance. +1. Verify the config is as expected `git config --global --get-urlmatch credential https://gitlab.example.com` ### Clearing config -``` +```console git config --global --unset-all credential.https://gitlab.example.com.GitLabDevClientId git config --global --unset-all credential.https://gitlab.example.com.GitLabDevClientSecret git config --global --unset-all credential.https://gitlab.example.com.provider @@ -23,22 +23,24 @@ To use on another instance, eg. `https://gitlab.example.com` requires setup and ## Preferences -``` +```console Select an authentication method for 'https://gitlab.com/': 1. Web browser (default) 2. Personal access token 3. Username/password -option (enter for default): +option (enter for default): ``` If you have a preferred authentication mode, you can specify [credential.gitLabAuthModes](configuration.md#credential.gitLabAuthModes): - `git config --global credential.gitlabauthmodes browser` +```console +git config --global credential.gitlabauthmodes browser +``` ## Caveats Improved support requires changes in GitLab. Please vote for these issues if they affect you: -1. No support for OAuth device authorization (necessary for machines without web browser) https://gitlab.com/gitlab-org/gitlab/-/issues/332682 -2. Only domains with prefix `gitlab.` are recognised as GitLab remotes https://gitlab.com/gitlab-org/gitlab/-/issues/349464 -3. Username/password authentication is suggested even if disabled on server https://gitlab.com/gitlab-org/gitlab/-/issues/349463 +1. No support for OAuth device authorization (necessary for machines without web browser): [GitLab issue 332682](https://gitlab.com/gitlab-org/gitlab/-/issues/332682) +1. Only domains with prefix `gitlab.` are recognised as GitLab remotes: [GitLab issue 349464](https://gitlab.com/gitlab-org/gitlab/-/issues/349464) +1. Username/password authentication is suggested even if disabled on server: [GitLab issue 349463](https://gitlab.com/gitlab-org/gitlab/-/issues/349463) diff --git a/docs/migration.md b/docs/migration.md index a2be4cfe7..88ba8da89 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -10,12 +10,12 @@ Because both Basic HTTP authentication and Windows Integrated Authentication (WI The following table shows the correct replacement for all legacy authorities values: -GCM_AUTHORITY
(credential.authority)|→|GCM_PROVIDER
(credential.provider)|GCM_ALLOW_WINDOWSAUTH
(credential.allowWindowsAuth) +GCM_AUTHORITY (credential.authority)|→|GCM_PROVIDER (credential.provider)|GCM_ALLOW_WINDOWSAUTH (credential.allowWindowsAuth) -|-|-|- -`msa`, `microsoft`, `microsoftaccount`,
`aad`, `azure`, `azuredirectory`,
`live`, `liveconnect`, `liveid`|→|`azure-repos`|_N/A_ +`msa`, `microsoft`, `microsoftaccount`, `aad`, `azure`, `azuredirectory`, `live`, `liveconnect`, `liveid`|→|`azure-repos`|_N/A_ `github`|→|`github`|_N/A_ `basic`|→|`generic`|`false` -`integrated`, `windows`, `kerberos`, `ntlm`,
`tfs`, `sso`|→|`generic`|`true` _(default)_ +`integrated`, `windows`, `kerberos`, `ntlm`, `tfs`, `sso`|→|`generic`|`true` _(default)_ For example if you had previous set the authority for the `example.com` host to `basic`.. diff --git a/docs/multiple-users.md b/docs/multiple-users.md index 20f1fd3cf..7446aef0e 100644 --- a/docs/multiple-users.md +++ b/docs/multiple-users.md @@ -10,11 +10,11 @@ Separate from the user strings in commits, Git recognizes the "user" part of a r Git hosting providers (like GitHub or Bitbucket) _do_ have a concept of "user". Typically it's an identity like a username or email address, plus a password or other credential to perform actions as that user. You may have guessed by now that GCM (the Git **Credential** Manager) does work with this notion of a user. -## People, identities, credentials, oh my! +## People, identities, credentials, oh my -You (a physical person) may have one or more user accounts (identities) with one or more Git hosting providers. Since most Git hosts don't put a "user" part in their URLs, by default, Git will treat the user part for a remote as the empty string. If you have multiple identites on one domain, you'll need to insert a unique user part per-identity yourself. +You (a physical person) may have one or more user accounts (identities) with one or more Git hosting providers. Since most Git hosts don't put a "user" part in their URLs, by default, Git will treat the user part for a remote as the empty string. If you have multiple identities on one domain, you'll need to insert a unique user part per-identity yourself. -There are good reasons for having multiple identities on one domain. You might use one GitHub identity for your personal work, another for your open source work, and a third for your employer's work. You can ask Git to assign a different credential to different repositories hosted on the same provider. HTTPS URLs include an optional "name" part before an `@` sign in the domain name, and you can use this to force Git to distiguish multiple users. This should likely be your username on the Git hosting service, since there are cases where GCM will use it like a username. +There are good reasons for having multiple identities on one domain. You might use one GitHub identity for your personal work, another for your open source work, and a third for your employer's work. You can ask Git to assign a different credential to different repositories hosted on the same provider. HTTPS URLs include an optional "name" part before an `@` sign in the domain name, and you can use this to force Git to distinguish multiple users. This should likely be your username on the Git hosting service, since there are cases where GCM will use it like a username. ## Setting it up diff --git a/docs/netconfig.md b/docs/netconfig.md index 7a6d5f51c..35cf9dc80 100644 --- a/docs/netconfig.md +++ b/docs/netconfig.md @@ -49,11 +49,11 @@ GCM supports other ways of configuring a proxy for convenience and compatibility 1. GCM-specific configuration options (_**only** respected by GCM; **deprecated**_): - `credential.httpProxy` - `credential.httpsProxy` -2. cURL environment variables (_also respected by Git_): +1. cURL environment variables (_also respected by Git_): - `http_proxy` - `https_proxy`/`HTTPS_PROXY` - `all_proxy`/`ALL_PROXY` -3. `GCM_HTTP_PROXY` environment variable (_**only** respected by GCM; **deprecated**_) +1. `GCM_HTTP_PROXY` environment variable (_**only** respected by GCM; **deprecated**_) Note that with the cURL environment variables there are both lowercase and uppercase variants. @@ -76,7 +76,7 @@ addresses. GCM supports the cURL environment variable `no_proxy` (and Like with the [other cURL proxy environment variables](#other-proxy-options), the lowercase variant will take precedence over the uppercase form. -This environment variable should contain a comma (`,`) or space (` `) separated +This environment variable should contain a comma-separated or space-separated list of host names that should not be proxied (should connect directly). GCM attempts to match [libcurl's behaviour](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html), diff --git a/docs/windows-broker.md b/docs/windows-broker.md index 1ab1cc73b..62b422ee5 100644 --- a/docs/windows-broker.md +++ b/docs/windows-broker.md @@ -31,6 +31,7 @@ The GCM team isn't responsible for the user experience or choices made by WAM, b Therefore, we want you to be aware of some defaults and experiences if you choose to use WAM integration. ### For work or school accounts (Azure AD-backed identities) + When you sign into an Azure DevOps organization backed by Azure AD (often your company or school email), if your machine is already joined to Azure AD matching that Azure DevOps organization, you'll get a seamless and easy-to-use experience. If your machine isn't Azure AD-joined, or is Azure AD-joined to a different tenant, WAM will present you with a dialog box suggesting you stay signed in and allow the organization to manage your device. @@ -57,6 +58,7 @@ Similar to the above, your organization's Conditional Access policies may preven If Conditional Access is required to access your organization's Git repositories, you can [enable WAM integration](environment.md#GCM_MSAUTH_USEBROKER-experimental) (or follow other instructions your organization provides). #### Removing device management + If you've allowed your computer to be managed and want to undo it, you can go into **Settings**, **Accounts**, **Access work or school**. In the section where you see your email address and organization name, click **Disconnect**. @@ -65,6 +67,7 @@ In the section where you see your email address and organization name, click **D ![Disconnecting from Azure AD](img/aad-disconnect.png) ### For Microsoft accounts + When you sign into an Azure DevOps organization backed by Microsoft account (MSA) identities (email addresses like `@outlook.com` or `@gmail.com` fall into this category), you may be prompted to select an existing "work or school account" or use a different one. In order to sign in with an MSA you should continue and select "Use a different [work or school] account", but enter your MSA credentials when prompted. @@ -81,8 +84,9 @@ For any connected MSA, you can control whether or not the account is available t ![Microsoft apps must ask to access your identity](img/apps-must-ask.png) Two very important things to note: -* If you haven't connected any Microsoft accounts to Windows before, the first account you connect will cause the local Windows user account to be converted to a connected account. -* In addition, you can't change the usage preference for the first Microsoft account connected to Windows: all Microsoft apps will be able to sign you in with that account. + +- If you haven't connected any Microsoft accounts to Windows before, the first account you connect will cause the local Windows user account to be converted to a connected account. +- In addition, you can't change the usage preference for the first Microsoft account connected to Windows: all Microsoft apps will be able to sign you in with that account. As far as we can tell, there are no workarounds for either of these behaviors (other than to not use the WAM broker). diff --git a/docs/wsl.md b/docs/wsl.md index 63b99e9ea..ccf606b18 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -102,7 +102,7 @@ installation, and not shared with others or the Windows host. Yes. Rather than install GCM as a Windows application (and have WSL Git invoke the Windows GCM), can you install GCM as a Linux application instead. -To do this, simply follow the [GCM installation instructions for Linux](../README.md#linux-install-instructions). +To do this, simply follow the [GCM installation instructions for Linux](../README.md#linux). **Note:** In this scenario, because GCM is running as a Linux application it cannot utilize authentication or credential storage features of the host