github: add multi-account prompt and login/logout commands (#1267)

Add multi-account support for the GitHub host provider.

Previously it was possible to use multiple accounts with GitHub, but
this required prior knowledge about including the username in the remote
URL (e.g. `https://[email protected]/mona/test`), and without this the
incorrect account may be selected, and subsequently erased due to
insufficient permissions.

This PR adds a few different features and prompts to improve
discoverability and experience using multiple GitHub accounts with GCM:

1. Add `login`, `logout` and `list` commands for the GitHub provider
2. Add UI and TTY prompts to select between GitHub user accounts
3. Abridged documentation and links to quickly discover the
'user-in-remote-URL' functionality
4. (bonus!) Ability to suppress GUI prompts over text-based ones via the
command-line using `--no-ui`

One thing that is absent compared to the Azure Repos provider's
multi-account support is the lack of account 'binding'. This is due to
lack of knowledge, by default, of the full remote URL from Git to be
able to discern between different repositories or organisations on the
same host.

**Command-line usage:**

```console
% git-credential-manager github --help    
Description:
  Commands for interacting with the GitHub host provider

Usage:
  git-credential-manager github [command] [options]

Options:
  --no-ui         Do not use graphical user interface prompts
  -?, -h, --help  Show help and usage information

Commands:
  list              List all known GitHub accounts.
  login             Add a GitHub account.
  logout <account>  Remove a GitHub account.
```
```console
% git-credential-manager github login --help
Description:
  Add a GitHub account.

Usage:
  git-credential-manager github login [options]

Options:
  --url <url>             URL of the GitHub instance to target, otherwise use GitHub.com
  --username <username>   User name to authenticate with
  --device                Use device flow to authenticate
  --browser, --web        Use a web browser to authenticate
  --pat, --token <token>  Use personal access token to authenticate
  --no-ui                 Do not use graphical user interface prompts
  -?, -h, --help          Show help and usage information
```
```console
% git-credential-manager github logout --help 
Description:
  Remove a GitHub account.

Usage:
  git-credential-manager github logout <account> [options]

Arguments:
  <account>  Account to remove

Options:
  --url <url>     URL of the GitHub instance to target, otherwise use GitHub.com
  --no-ui         Do not use graphical user interface prompts
  -?, -h, --help  Show help and usage information
```
```console
% git-credential-manager github list --help  
Description:
  List all known GitHub accounts.

Usage:
  git-credential-manager github list [options]

Options:
  --url <url>     URL of the GitHub instance to target, otherwise use GitHub.com
  --no-ui         Do not use graphical user interface prompts
  -?, -h, --help  Show help and usage information
```

**Select account UI prompts:**

Avalonia|Windows legacy helper (WPF)
-|-
<img width="532" alt="image"
src="https://github.com/git-ecosystem/git-credential-manager/assets/5658207/e7fc0ab9-903a-466b-9424-26183c188652">|![image](https://github.com/git-ecosystem/git-credential-manager/assets/5658207/6b2fa7bb-2e62-435f-a187-72f42734ced0)

Author: mjcheetham

docs/multiple-users.md

@@ -4,6 +4,15 @@ 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.
 
+---
+
+**Prompted to select an account?**
+
+Read the [**TL;DR** section][tldr] below for a quick summary of how to make GCM
+remember which account to use for which repository.
+
+---
+
 ## Foundations: Git and Git hosts
 
 Git itself doesn't have a single, strong concept of "user". There's the
@@ -79,3 +88,35 @@ git remote set-url origin https://[email protected]/big-company/secret-re
 which you should also be aware of if you're using it.
 
 [azure-access-tokens]: azrepos-users-and-tokens.md
+
+## GitHub
+
+You can use the `github [list | login | logout]` commands to manage your GitHub
+accounts. These commands are documented in the [command-line usage][cli-usage]
+or by running `git-credential-manager github --help`.
+
+## TL;DR: Tell GCM to remember which account to use
+
+The easiest way to have GCM remember which account to use for which repository
+is to include the account name in the remote URL. If you're using HTTPS remotes,
+you can include the account name in the URL by inserting it before the `@` sign
+in the domain name.
+
+For example, if you want to always use the `alice` account for the `mona/test`
+GitHub repository, you can clone it using the `alice` account by running:
+
+```shell
+git clone https://[email protected]/mona/test
+```
+
+To update an existing clone, you can run `git remote set-url` to update the URL:
+
+```shell
+git remote set-url origin https://[email protected]/mona/test
+```
+
+If your account name includes an `@` then remember to escape this character
+using `%40`: `https://alice%[email protected]/test`.
+
+[tldr]: #tldr-tell-gcm-to-remember-which-account-to-use
+[cli-usage]: usage.md

docs/usage.md

@@ -46,3 +46,8 @@ For more information about managing user account bindings see
 
 [azure-access-tokens-ua]: azrepos-users-and-tokens.md#useraccounts
 [git-credentials-custom-helpers]: https://git-scm.com/docs/gitcredentials#_custom_helpers
+
+### github
+
+Interact with the GitHub host provider to manage your accounts on GitHub.com and
+GitHub Enterprise Server instances.

src/shared/Core.Tests/Authentication/BasicAuthenticationTests.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Threading.Tasks;
 using GitCredentialManager.Authentication;
 using GitCredentialManager.Tests.Objects;
@@ -101,7 +102,7 @@ public async Task BasicAuthentication_GetCredentials_DesktopSession_UIHelper_Cal
             auth.Setup(x => x.InvokeHelperAsync(
                     It.IsAny<string>(),
                     $"basic --resource {testResource}",
-                    It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<StreamReader>(),
                     It.IsAny<System.Threading.CancellationToken>()))
                 .ReturnsAsync(
                     new Dictionary<string, string>
@@ -147,7 +148,7 @@ public async Task BasicAuthentication_GetCredentials_DesktopSession_UIHelper_Use
             auth.Setup(x => x.InvokeHelperAsync(
                     It.IsAny<string>(),
                     $"basic --resource {testResource} --username {testUserName}",
-                    It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<StreamReader>(),
                     It.IsAny<System.Threading.CancellationToken>()))
                 .ReturnsAsync(
                     new Dictionary<string, string>

src/shared/Core/Application.cs

@@ -4,7 +4,6 @@
 using System.CommandLine.Builder;
 using System.CommandLine.Invocation;
 using System.CommandLine.Parsing;
-using System.IO;
 using System.Linq;
 using System.Text.RegularExpressions;
 using System.Threading.Tasks;
@@ -70,6 +69,18 @@ protected override async Task<int> RunInternalAsync(string[] args)
             var rootCommand = new RootCommand();
             var diagnoseCommand = new DiagnoseCommand(Context);
 
+            // Add common options
+            var noGuiOption = new Option<bool>("--no-ui", "Do not use graphical user interface prompts");
+            rootCommand.AddGlobalOption(noGuiOption);
+
+            void NoGuiOptionHandler(InvocationContext context)
+            {
+                if (context.ParseResult.HasOption(noGuiOption))
+                {
+                    Context.Settings.IsGuiPromptsEnabled = false;
+                }
+            }
+
             // Add standard commands
             rootCommand.AddCommand(new GetCommand(Context, _providerRegistry));
             rootCommand.AddCommand(new StoreCommand(Context, _providerRegistry));
@@ -103,6 +114,7 @@ protected override async Task<int> RunInternalAsync(string[] args)
             var parser = new CommandLineBuilder(rootCommand)
                 .UseDefaults()
                 .UseExceptionHandler(OnException)
+                .AddMiddleware(NoGuiOptionHandler)
                 .Build();
 
             return await parser.InvokeAsync(args);

src/shared/Core/Authentication/AuthenticationBase.cs

@@ -21,13 +21,13 @@ protected AuthenticationBase(ICommandContext context)
         }
 
         protected Task<IDictionary<string, string>> InvokeHelperAsync(string path, string args,
-            IDictionary<string, string> standardInput = null)
+            StreamReader standardInput = null)
         {
-            return InvokeHelperAsync(path, args, null, CancellationToken.None);
+            return InvokeHelperAsync(path, args, standardInput, CancellationToken.None);
         }
 
         protected internal virtual async Task<IDictionary<string, string>> InvokeHelperAsync(string path, string args,
-            IDictionary<string, string> standardInput, CancellationToken ct)
+            StreamReader standardInput, CancellationToken ct)
         {
             var procStartInfo = new ProcessStartInfo(path)
             {
@@ -56,9 +56,15 @@ protected internal virtual async Task<IDictionary<string, string>> InvokeHelperA
             // Kill the process upon a cancellation request
             ct.Register(() => process.Kill());
 
-            if (!(standardInput is null))
+            // Write the standard input to the process if we have any to write
+            if (standardInput is not null)
             {
-                await process.StandardInput.WriteDictionaryAsync(standardInput);
+#if NETFRAMEWORK
+                await standardInput.BaseStream.CopyToAsync(process.StandardInput.BaseStream);
+#else
+                await standardInput.BaseStream.CopyToAsync(process.StandardInput.BaseStream, ct);
+#endif
+                process.StandardInput.Close();
             }
 
             IDictionary<string, string> resultDict = await process.StandardOutput.ReadDictionaryAsync(StringComparer.OrdinalIgnoreCase);

src/shared/Core/CommandExtensions.cs

@@ -0,0 +1,95 @@
+using System;
+using System.Collections.Generic;
+using System.CommandLine;
+using System.Diagnostics;
+using System.Linq;
+
+namespace GitCredentialManager;
+
+public static class CommandExtensions
+{
+    /// <summary>
+    /// Add options to a command.
+    /// </summary>
+    /// <param name="command">Command to add options to.</param>
+    /// <param name="arity">Specify the required arity of the options.</param>
+    /// <param name="options">Set of options to add.</param>
+    public static void AddOptionSet(this Command command, OptionArity arity, params Option[] options)
+    {
+        foreach (Option option in options)
+        {
+            command.AddOption(option);
+        }
+
+        // No need to add a validator if 0..* options are OK
+        if (arity != OptionArity.ZeroOrMore)
+        {
+            command.AddValidator(r =>
+            {
+                int count = options.Count(o => r.FindResultFor(o) is not null);
+                string optionList = string.Join(", ", options.Select(s => $"--{s.Name}"));
+                switch (arity)
+                {
+                    case OptionArity.ZeroOrOne:
+                        if (count > 1)
+                            r.ErrorMessage = $"Can only specify one of: {optionList}";
+                        break;
+
+                    case OptionArity.ExactlyOne:
+                        if (count != 1)
+                            r.ErrorMessage = $"Require exactly one of: {optionList}";
+                        break;
+
+                    case OptionArity.Zero:
+                        if (count != 0)
+                        {
+                            IEnumerable<string> usedOptions = options.Where(o => r.FindResultFor(o) is not null)
+                                .Select(x => $"--{x.Name}");
+                            r.ErrorMessage = $"{command.Name} does not support options: {string.Join(", ", usedOptions)}";
+                        }
+                        break;
+
+                    case OptionArity.OneOrMore:
+                        if (count == 0)
+                            r.ErrorMessage = $"Require at least one of: {optionList}";
+                        break;
+
+                    case OptionArity.ZeroOrMore:
+                        Debug.Fail("Should not have a validator for an arity of ZeroOrMore.");
+                        break;
+
+                    default:
+                        throw new ArgumentOutOfRangeException(nameof(arity), arity, null);
+                }
+            });
+        }
+    }
+}
+
+public enum OptionArity
+{
+    /// <summary>
+    /// An arity that may have multiple values.
+    /// </summary>
+    ZeroOrMore = 0,
+
+    /// <summary>
+    /// An arity that must have exactly one value.
+    /// </summary>
+    ExactlyOne,
+
+    /// <summary>
+    /// An arity that does not allow any values.
+    /// </summary>
+    Zero,
+
+    /// <summary>
+    /// An arity that may have one value, but no more than one.
+    /// </summary>
+    ZeroOrOne,
+
+    /// <summary>
+    /// An arity that must have at least one value.
+    /// </summary>
+    OneOrMore,
+}

src/shared/Core/Constants.cs

@@ -211,6 +211,7 @@ public static class HelpUrls
             public const string GcmAutoDetect          = "https://aka.ms/gcm/autodetect";
             public const string GcmExecRename          = "https://aka.ms/gcm/rename";
             public const string GcmDefaultAccount      = "https://aka.ms/gcm/defaultaccount";
+            public const string GcmMultipleUsers       = "https://aka.ms/gcm/multipleusers";
         }
 
         private static Version _gcmVersion;

src/shared/Core/CredentialCacheStore.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 
 namespace GitCredentialManager
@@ -22,6 +23,25 @@ public CredentialCacheStore(IGit git, string options)
 
         #region ICredentialStore
 
+        public IList<string> GetAccounts(string service)
+        {
+            // Listing accounts is not supported by the credential-cache store so we just attempt to retrieve
+            // the username from first credential for the given service and return an empty list if it fails.
+            var input = MakeGitCredentialsEntry(service, null);
+
+            var result = _git.InvokeHelperAsync(
+                $"credential-cache get {_options}",
+                input
+            ).GetAwaiter().GetResult();
+
+            if (result.TryGetValue("username", out string value))
+            {
+                return new List<string> { value };
+            }
+
+            return Array.Empty<string>();
+        }
+
         public ICredential Get(string service, string account)
         {
             var input = MakeGitCredentialsEntry(service, account);

src/shared/Core/CredentialStore.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
 using System.Text;
 using GitCredentialManager.Interop.Linux;
@@ -24,6 +25,12 @@ public CredentialStore(ICommandContext context)
 
         #region ICredentialStore
 
+        public IList<string> GetAccounts(string service)
+        {
+            EnsureBackingStore();
+            return _backingStore.GetAccounts(service);
+        }
+
         public ICredential Get(string service, string account)
         {
             EnsureBackingStore();

src/shared/Core/ICredentialStore.cs

@@ -1,3 +1,4 @@
+using System.Collections.Generic;
 
 namespace GitCredentialManager
 {
@@ -6,6 +7,13 @@ namespace GitCredentialManager
     /// </summary>
     public interface ICredentialStore
     {
+        /// <summary>
+        /// Get all accounts from the store for the given service.
+        /// </summary>
+        /// <param name="service">Name of the service to match against. Use null to match all values.</param>
+        /// <returns>All accounts that match the query.</returns>
+        IList<string> GetAccounts(string service);
+
         /// <summary>
         /// Get the first credential from the store that matches the given query.
         /// </summary>