Merge pull request cli#1696 from cli/env-help-topic

Extract environment variables as a separate help topic

pkg/cmd/root/help.go

@@ -139,7 +139,7 @@ func rootHelpFunc(command *cobra.Command, args []string) {
 		helpEntries = append(helpEntries, helpEntry{"ENVIRONMENT VARIABLES", command.Annotations["help:environment"]})
 	}
 	helpEntries = append(helpEntries, helpEntry{"LEARN MORE", `
-Use "gh <command> <subcommand> --help" for more information about a command.
+Use 'gh <command> <subcommand> --help' for more information about a command.
 Read the manual at https://cli.github.com/manual`})
 	if _, ok := command.Annotations["help:feedback"]; ok {
 		helpEntries = append(helpEntries, helpEntry{"FEEDBACK", command.Annotations["help:feedback"]})

pkg/cmd/root/help_topic.go

@@ -0,0 +1,58 @@
+package root
+
+import (
+	"github.com/MakeNowJust/heredoc"
+	"github.com/spf13/cobra"
+)
+
+func NewHelpTopic(topic string) *cobra.Command {
+	topicContent := make(map[string]string)
+
+	topicContent["environment"] = heredoc.Doc(`
+		GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids
+		being prompted to authenticate and takes precedence over previously stored credentials.
+
+		GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise.
+
+		GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands
+		that otherwise operate on a local repository.
+
+		GH_HOST: specify the GitHub hostname for commands that would otherwise assume
+		the "github.com" host when not in a context of an existing repository.
+
+		GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use
+		for authoring text.
+
+		BROWSER: the web browser to use for opening links.
+
+		DEBUG: set to any value to enable verbose output to standard error. Include values "api"
+		or "oauth" to print detailed information about HTTP requests or authentication flow.
+
+		GLAMOUR_STYLE: the style to use for rendering Markdown. See
+		https://github.com/charmbracelet/glamour#styles
+
+		NO_COLOR: avoid printing ANSI escape sequences for color output.
+	`)
+
+	cmd := &cobra.Command{
+		Use:    topic,
+		Long:   topicContent[topic],
+		Hidden: true,
+		Args:   cobra.NoArgs,
+		Run:    helpTopicHelpFunc,
+	}
+
+	cmd.SetHelpFunc(helpTopicHelpFunc)
+	cmd.SetUsageFunc(helpTopicUsageFunc)
+
+	return cmd
+}
+
+func helpTopicHelpFunc(command *cobra.Command, args []string) {
+	command.Print(command.Long)
+}
+
+func helpTopicUsageFunc(command *cobra.Command) error {
+	command.Printf("Usage: gh help %s", command.Use)
+	return nil
+}

pkg/cmd/root/help_topic_test.go

@@ -0,0 +1,79 @@
+package root
+
+import (
+	"testing"
+
+	"github.com/cli/cli/pkg/iostreams"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewHelpTopic(t *testing.T) {
+	tests := []struct {
+		name     string
+		topic    string
+		args     []string
+		flags    []string
+		wantsErr bool
+	}{
+		{
+			name:     "valid topic",
+			topic:    "environment",
+			args:     []string{},
+			flags:    []string{},
+			wantsErr: false,
+		},
+		{
+			name:     "invalid topic",
+			topic:    "invalid",
+			args:     []string{},
+			flags:    []string{},
+			wantsErr: false,
+		},
+		{
+			name:     "more than zero args",
+			topic:    "environment",
+			args:     []string{"invalid"},
+			flags:    []string{},
+			wantsErr: true,
+		},
+		{
+			name:     "more than zero flags",
+			topic:    "environment",
+			args:     []string{},
+			flags:    []string{"--invalid"},
+			wantsErr: true,
+		},
+		{
+			name:     "help arg",
+			topic:    "environment",
+			args:     []string{"help"},
+			flags:    []string{},
+			wantsErr: true,
+		},
+		{
+			name:     "help flag",
+			topic:    "environment",
+			args:     []string{},
+			flags:    []string{"--help"},
+			wantsErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, _, stdout, stderr := iostreams.Test()
+
+			cmd := NewHelpTopic(tt.topic)
+			cmd.SetArgs(append(tt.args, tt.flags...))
+			cmd.SetOut(stdout)
+			cmd.SetErr(stderr)
+
+			_, err := cmd.ExecuteC()
+			if tt.wantsErr {
+				assert.Error(t, err)
+				return
+			}
+			assert.NoError(t, err)
+		})
+	}
+}

pkg/cmd/root/root.go

@@ -41,32 +41,10 @@ func NewCmdRoot(f *cmdutil.Factory, version, buildDate string) *cobra.Command {
 		`),
 		Annotations: map[string]string{
 			"help:feedback": heredoc.Doc(`
-				Open an issue using “gh issue create -R cli/cli”
+				Open an issue using 'gh issue create -R cli/cli'
 			`),
 			"help:environment": heredoc.Doc(`
-				GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids
-				being prompted to authenticate and takes precedence over previously stored credentials.
-	
-				GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise.
-	
-				GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands
-				that otherwise operate on a local repository.
-
-				GH_HOST: specify the GitHub hostname for commands that would otherwise assume
-				the "github.com" host when not in a context of an existing repository.
-	
-				GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use
-				for authoring text.
-	
-				BROWSER: the web browser to use for opening links.
-	
-				DEBUG: set to any value to enable verbose output to standard error. Include values "api"
-				or "oauth" to print detailed information about HTTP requests or authentication flow.
-	
-				GLAMOUR_STYLE: the style to use for rendering Markdown. See
-				https://github.com/charmbracelet/glamour#styles
-	
-				NO_COLOR: avoid printing ANSI escape sequences for color output.
+				See 'gh help environment' for the list of supported environment variables.
 			`),
 		},
 	}
@@ -104,15 +82,17 @@ func NewCmdRoot(f *cmdutil.Factory, version, buildDate string) *cobra.Command {
 
 	cmdutil.DisableAuthCheck(cmd)
 
-	// CHILD COMMANDS
-
+	// Child commands
 	cmd.AddCommand(aliasCmd.NewCmdAlias(f))
 	cmd.AddCommand(authCmd.NewCmdAuth(f))
 	cmd.AddCommand(configCmd.NewCmdConfig(f))
 	cmd.AddCommand(creditsCmd.NewCmdCredits(f, nil))
 	cmd.AddCommand(gistCmd.NewCmdGist(f))
 	cmd.AddCommand(NewCmdCompletion(f.IOStreams))
 
+	// Help topics
+	cmd.AddCommand(NewHelpTopic("environment"))
+
 	// the `api` command should not inherit any extra HTTP headers
 	bareHTTPCmdFactory := *f
 	bareHTTPCmdFactory.HttpClient = func() (*http.Client, error) {