diff --git a/docs/multiple-accounts.md b/docs/multiple-accounts.md index 67b6fa0b5..29c83b703 100644 --- a/docs/multiple-accounts.md +++ b/docs/multiple-accounts.md @@ -8,7 +8,7 @@ A particular shoutout to @gabe565 and his long term community support for https: With the release of `v2.40.0`, `gh` has begun supporting multiple accounts for some use cases on github.com and in GitHub Enterprise. We recognise that there are a number of missing quality of life features, and we've opted -not to address the use case of automatic account switching based on some context (e.g. `pwd`, `git remote`, etc). +not to address the use case of automatic account switching based on some context (e.g. `pwd`, `git remote`). However, we hope many of those using these custom solutions will now find it easier to obtain and update tokens (via the standard OAuth flow rather than as a PAT), and to store them securely in the system keyring managed by `gh`. @@ -111,7 +111,7 @@ if there are any remaining logged into the host: As mentioned above, we know that this only addresses some of the requests around supporting multiple accounts. While these are not out of scope forever, for this release some of the big things we have intentionally not included are: - * Automatic account switching based on some context (e.g. `pwd`, `git remote`, etc) + * Automatic account switching based on some context (e.g. `pwd`, `git remote`) * Automatic configuration of git config such as `user.name` and `user.email` when switching * User level configuration e.g. `williammartin` uses `vim` but `wilmartin_microsoft` uses `emacs` diff --git a/pkg/cmd/auth/refresh/refresh.go b/pkg/cmd/auth/refresh/refresh.go index a918493e8..b77c45bac 100644 --- a/pkg/cmd/auth/refresh/refresh.go +++ b/pkg/cmd/auth/refresh/refresh.go @@ -55,7 +55,7 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra. Use: "refresh", Args: cobra.ExactArgs(0), Short: "Refresh stored authentication credentials", - Long: heredoc.Docf(`Expand or fix the permission scopes for stored credentials. + Long: heredoc.Docf(`Expand or fix the permission scopes for stored credentials for active account. The %[1]s--scopes%[1]s flag accepts a comma separated list of scopes you want your gh credentials to have. If no scopes are provided, the command @@ -67,6 +67,10 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra. The %[1]s--reset-scopes%[1]s flag resets the scopes for your gh credentials to the default set of scopes for your auth flow. + + If you have multiple accounts in %[1]sgh auth status%[1]s and want to refresh the credentials for an + inactive account, you will have to use %[1]sgh auth switch%[1]s to that account first before using + this command, and then switch back when you are done. `, "`"), Example: heredoc.Doc(` $ gh auth refresh --scopes write:org,read:public_key diff --git a/pkg/cmd/auth/status/status.go b/pkg/cmd/auth/status/status.go index fa027e193..c28c3f48e 100644 --- a/pkg/cmd/auth/status/status.go +++ b/pkg/cmd/auth/status/status.go @@ -140,7 +140,7 @@ func NewCmdStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "status", Args: cobra.ExactArgs(0), - Short: "View authentication status", + Short: "View all accounts and authentication status", Long: heredoc.Doc(`Verifies and displays information about your authentication state. This command will test your authentication state for each GitHub host that gh knows about and diff --git a/pkg/cmd/auth/switch/switch.go b/pkg/cmd/auth/switch/switch.go index 129fe9fd4..bc94ff8c4 100644 --- a/pkg/cmd/auth/switch/switch.go +++ b/pkg/cmd/auth/switch/switch.go @@ -32,12 +32,14 @@ func NewCmdSwitch(f *cmdutil.Factory, runF func(*SwitchOptions) error) *cobra.Co Use: "switch", Args: cobra.ExactArgs(0), Short: "Switch active GitHub account", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Switch the active account for a GitHub host. This command changes the authentication configuration that will be used when running commands targeting the specified GitHub host. - `), + + For a list of authenticated accounts you can run %[1]sgh auth status%[1]s. + `, "`"), Example: heredoc.Doc(` # Select what host and account to switch to via a prompt $ gh auth switch