Improve user-friendliness of completion command

mislav · mislav · commit 2915abc2ba8e · 2020-04-07T16:58:50.000+02:00
When ran directly in the terminal, the command now errors out with:

    $ gh completion
    error: the value for `--shell` is required
    see `gh completion --help` for more information

This is to avoid the previously default bash code output confusing the
user if they ran the command out of curiousity.

A backwards compatibility layer is present here: if stdout is not a
terminal, then output bash code like before. This is to support users
who have already added a line like this to their bash profile:

    eval "$(gh completion)"
diff --git a/command/completion.go b/command/completion.go
@@ -1,25 +1,31 @@
 package command
 
 import (
+	"errors"
 	"fmt"
+	"os"
 
 	"github.com/cli/cli/internal/cobrafish"
+	"github.com/cli/cli/utils"
 	"github.com/spf13/cobra"
 )
 
 func init() {
 	RootCmd.AddCommand(completionCmd)
-	completionCmd.Flags().StringP("shell", "s", "bash", "Shell type: {bash|zsh|fish|powershell}")
+	completionCmd.Flags().StringP("shell", "s", "", "Shell type: {bash|zsh|fish|powershell}")
 }
 
 var completionCmd = &cobra.Command{
 	Use:   "completion",
 	Short: "Generate shell completion scripts",
 	Long: `Generate shell completion scripts for GitHub CLI commands.
 
+The output of this command will be computer code and is meant to be saved to a
+file or immediately evaluated by an interactive shell.
+
 For example, for bash you could add this to your '~/.bash_profile':
 
-	eval "$(gh completion)"
+	eval "$(gh completion -s bash)"
 
 When installing GitHub CLI through a package manager, however, it's possible that
 no additional shell configuration is necessary to gain completion support. For
@@ -31,6 +37,19 @@ Homebrew, see <https://docs.brew.sh/Shell-Completion>
 			return err
 		}
 
+		if shellType == "" {
+			out := cmd.OutOrStdout()
+			isTTY := false
+			if outFile, isFile := out.(*os.File); isFile {
+				isTTY = utils.IsTerminal(outFile)
+			}
+
+			if isTTY {
+				return errors.New("error: the value for `--shell` is required\nsee `gh help completion` for more information")
+			}
+			shellType = "bash"
+		}
+
 		switch shellType {
 		case "bash":
 			return RootCmd.GenBashCompletion(cmd.OutOrStdout())
