Merge pull request #547 from GitCredentialManager/vtbassmatt-fixes

vtbassmatt · web-flow · commit e2787941a53e · 2021-11-22T15:09:22.000-05:00
Batch of documentation fixes
diff --git a/README.md b/README.md
@@ -101,6 +101,13 @@ __Note:__ Although packages were previously offered on certain
 GCM no longer publishes to these repositories. Please install the
 Debian package using the above instructions instead.
 
+To uninstall:
+
+```shell
+git-credential-manager-core unconfigure
+sudo dpkg -r gcmcore
+```
+
 #### Other distributions
 
 Download the latest [tarball](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following:
@@ -110,6 +117,13 @@ tar -xvf <path-to-tarball> -C /usr/local/bin
 git-credential-manager-core configure
 ```
 
+To uninstall:
+git-credential-manager-core unconfigure
+rm $(command -v git-credential-manager-core)
+```shell
+
+```
+
 **Note:** all Linux distributions [require additional configuration](https://aka.ms/gcm/credstores) to use GCM.
 
 ---
diff --git 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](#explicit-configuration)
+If a heuristic matches incorrectly, you can always [explicitly configure](#manual-configuration)
 GCM to use a particular provider.
 
 ## Remote URL probing
diff --git a/docs/faq.md b/docs/faq.md
@@ -82,3 +82,30 @@ We are happy to accept proposals and/or contributions to enable GCM to run on ot
 Due to the design of Git and credential helpers such as GCM, we need this setting to make Git use the full remote URL (including the path component) when communicating with GCM. The new `dev.azure.com` format of Azure DevOps URLs means the account name is now part of the path component (for example: `https://dev.azure.com/contoso/...`). The Azure DevOps account name is required in order to resolve the correct authority for authentication (which Azure AD tenant backs this account, or if it is backed by Microsoft personal accounts).
 
 In the older GCM for Windows product, the solution to the same problem was a "hack". GCM for Windows would walk the process tree looking for the `git-remote-https.exe` process, and attempt to read/parse the process environment block looking for the command line arguments (that contained the full remote URL). This is fragile and not a cross-platform solution, hense the need for the `credential.useHttpPath` setting with GCM.
+
+### Why does GCM take so long at startup the first time?
+
+GCM will [autodetect](autodetect.md) what kind of Git host it's talking to. GitHub, Bitbucket, and Azure DevOps each have their own form(s) of authentication, plus there's a "generic" username and password option.
+
+For the hosted versions of these services, GCM can guess from the URL which service to use. But for on-premises versions which would have unique URLs, GCM will probe with a network call. GCM caches the results of the probe, so it should be faster on the second and later invocations.
+
+If you know which provider you're talking to and want to avoid the probe, that's possible. You can explicitly tell GCM which provider to use for a URL "example.com" like this:
+
+|| Provider || Command ||
+|-----------|----------|
+| GitHub    | `git config --global credential.https://example.com.provider github`
+| Bitbucket | `git config --global credential.https://example.com.provider bitbucket`
+| Azure DevOps | `git config --global credential.https://example.com.provider azure-repos`
+| Generic | `git config --global credential.https://example.com.provider generic`
+
+### How do I fix "Could not create SSL/TLS secure channel" errors on Windows 7?
+
+This likely indicates that you don't have newer TLS versions available. Please [follow Microsoft's guide](https://support.microsoft.com/topic/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-winhttp-in-windows-c4bd73d2-31d7-761e-0178-11268bb10392) for enabling TLS 1.1 and 1.2 on your machine, specifically the **SChannel** instructions. You'll need to be on at least Windows 7 SP1, and in the end you should have a `TLS 1.2` key with `DisabledByDefault` set to `0`. You can also read [more from Microsoft](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn786418(v=ws.11)#tls-12) on this change.
+
+### How do I use GCM with Windows Subsystem for Linux (WSL)?
+
+Follow the instructions in [our WSL guide](wsl.md) carefully. Especially note the need to run `git config --global credential.https://dev.azure.com.useHttpPath true` _within_ WSL if you're using Azure DevOps.
+
+### Does GCM work with multiple users? If so, how?
+
+That's a fairly complicated question to answer, but in short, yes. See [our document on multiple users](multiple-users.md) for details.
diff --git a/docs/multiple-users.md b/docs/multiple-users.md
@@ -0,0 +1,53 @@
+# Multiple users
+
+If you work with multiple different identities on a single Git hosting service, you may be wondering if Git Credential Manager (GCM) supports this workflow. The answer is yes, with a bit of complexity due to how it interoperates with Git.
+
+## Foundations: Git and Git hosts
+
+Git itself doesn't have a single, strong concept of "user". There's the `user.name` and `user.email` which get embedded into commit headers/trailers, but these are arbitrary strings. GCM doesn't interact with this notion of a user at all. You can put whatever you want into your `user.*` config, and nothing in GCM will change at all.
+
+Separate from the user strings in commits, Git recognizes the "user" part of a remote URL or a credential. These are not often used, at least by default, in the web UI of major Git hosts.
+
+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!
+
+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.
+
+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.
+
+## Setting it up
+
+As an example, let's say you're working on multiple repositories hosted at the same domain name.
+
+| Repo URL | Identity |
+|----------|----------|
+| `https://example.com/open-source/library.git` | `contrib123` |
+| `https://example.com/more-open-source/app.git` | `contrib123` |
+| `https://example.com/big-company/secret-repo.git` | `employee9999` |
+
+When you clone these repos, include the identity and an `@` before the domain name in order to force Git and GCM to use different identities. If you've already cloned the repos, you can update the remote URL to incude the identity.
+
+### Example: fresh clones
+
+```shell
+# instead of `git clone https://example.com/open-source/library.git`, run:
+git clone https://contrib123@example.com/open-source/library.git
+
+# instead of `git clone https://example.com/big-company/secret-repo.git`, run:
+git clone https://employee9999@example.com/big-company/secret-repo.git
+```
+
+### Example: existing clones
+
+```shell
+# in the `library` repo, run:
+git remote set-url origin https://contrib123@example.com/open-source/library.git
+
+# in the `secret-repo` repo, run:
+git remote set-url origin https://employee9999@example.com/big-company/secret-repo.git
+```
+
+## Azure DevOps
+
+[Azure DevOps has some additional, optional complexity](azrepos-users-and-tokens.md) which you should also be aware of if you're using it.
