[cli] Have commands with rich output respect the `--color` flag

- default: `--color=auto`
- `--color` is equivalent to `--color=always`
- `--color=never` disables color for TTYs

commands/api.go

@@ -66,6 +66,10 @@ var cmdApi = &Command{
 		Parse response JSON and output the data in a line-based key-value format
 		suitable for use in shell scripts.
 
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 	--cache <TTL>
 		Cache successful responses to GET requests for <TTL> seconds.
 
@@ -205,7 +209,7 @@ func apiCommand(cmd *Command, args *Args) {
 	args.NoForward()
 
 	out := ui.Stdout
-	colorize := ui.IsTerminal(os.Stdout)
+	colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 	success := response.StatusCode < 300
 	parseJSON := args.Flag.Bool("--flat")
 

commands/ci_status.go

@@ -33,6 +33,10 @@ var cmdCiStatus = &Command{
 
 		%t: name of the status check
 
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 	<COMMIT>
 		A commit SHA or branch name (default: "HEAD").
 
@@ -122,7 +126,8 @@ func ciStatus(cmd *Command, args *Args) {
 
 		verbose := args.Flag.Bool("--verbose") || args.Flag.HasReceived("--format")
 		if verbose && len(response.Statuses) > 0 {
-			verboseFormat(response.Statuses, args.Flag.Value("--format"))
+			colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
+			ciVerboseFormat(response.Statuses, args.Flag.Value("--format"), colorize)
 		} else {
 			if state != "" {
 				ui.Println(state)
@@ -135,9 +140,7 @@ func ciStatus(cmd *Command, args *Args) {
 	}
 }
 
-func verboseFormat(statuses []github.CIStatus, formatString string) {
-	colorize := ui.IsTerminal(os.Stdout)
-
+func ciVerboseFormat(statuses []github.CIStatus, formatString string, colorize bool) {
 	contextWidth := 0
 	for _, status := range statuses {
 		if len(status.Context) > contextWidth {

commands/issue.go

@@ -109,6 +109,10 @@ With no arguments, show a list of open issues.
 
 		%%: a literal %
 
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 	-m, --message <MESSAGE>
 		The text up to the first blank line in <MESSAGE> is treated as the issue
 		title, and the rest is used as issue description in Markdown format.
@@ -173,6 +177,7 @@ hub-pr(1), hub(1)
 		-^, --sort-ascending
 		--include-pulls
 		-L, --limit N
+		--color
 `,
 	}
 
@@ -196,6 +201,7 @@ hub-pr(1), hub(1)
 		Run: showIssue,
 		KnownFlags: `
 		-f, --format FMT
+		--color
 `,
 	}
 
@@ -285,7 +291,7 @@ func listIssues(cmd *Command, args *Args) {
 			}
 		}
 
-		colorize := ui.IsTerminal(os.Stdout)
+		colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 		for _, issue := range issues {
 			ui.Print(formatIssue(issue, flagIssueFormat, colorize))
 		}
@@ -445,7 +451,7 @@ func showIssue(cmd *Command, args *Args) {
 
 	args.NoForward()
 
-	colorize := ui.IsTerminal(os.Stdout)
+	colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 	if args.Flag.HasReceived("--format") {
 		flagShowIssueFormat := args.Flag.Value("--format")
 		ui.Print(formatIssue(*issue, flagShowIssueFormat, colorize))
@@ -583,12 +589,22 @@ func listLabels(cmd *Command, args *Args) {
 	labels, err := gh.FetchLabels(project)
 	utils.Check(err)
 
-	flagLabelsColorize := args.Flag.Bool("--color")
+	flagLabelsColorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 	for _, label := range labels {
 		ui.Print(formatLabel(label, flagLabelsColorize))
 	}
 }
 
+func colorizeOutput(colorSet bool, when string) bool {
+	if !colorSet || when == "auto" {
+		return ui.IsTerminal(os.Stdout)
+	} else if when == "never" {
+		return false
+	} else {
+		return true // "always"
+	}
+}
+
 func formatLabel(label github.IssueLabel, colorize bool) string {
 	if colorize {
 		if color, err := utils.NewColor(label.Color); err == nil {

commands/pr.go

@@ -2,7 +2,6 @@ package commands
 
 import (
 	"fmt"
-	"os"
 	"strconv"
 	"strings"
 
@@ -117,6 +116,10 @@ pr checkout <PR-NUMBER> [<BRANCH>]
 
 		%%: a literal %
 
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 	-o, --sort <KEY>
 		Sort displayed issues by "created" (default), "updated", "popularity", or "long-running".
 
@@ -133,8 +136,9 @@ hub-issue(1), hub-pull-request(1), hub(1)
 	}
 
 	cmdCheckoutPr = &Command{
-		Key: "checkout",
-		Run: checkoutPr,
+		Key:        "checkout",
+		Run:        checkoutPr,
+		KnownFlags: "\n",
 	}
 
 	cmdListPulls = &Command{
@@ -210,7 +214,7 @@ func listPulls(cmd *Command, args *Args) {
 	})
 	utils.Check(err)
 
-	colorize := ui.IsTerminal(os.Stdout)
+	colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 	for _, pr := range pulls {
 		ui.Print(formatPullRequest(pr, flagPullRequestFormat, colorize))
 	}

commands/release.go

@@ -140,6 +140,10 @@ With '--exclude-prereleases', exclude non-stable releases from the listing.
 
 		%%: a literal %
 
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 	<TAG>
 		The git tag name for this release.
 
@@ -152,6 +156,7 @@ hub(1), git-tag(1)
 		-p, --exclude-prereleases
 		-L, --limit N
 		-f, --format FMT
+		--color
 `,
 	}
 
@@ -161,6 +166,7 @@ hub(1), git-tag(1)
 		KnownFlags: `
 		-d, --show-downloads
 		-f, --format FMT
+		--color
 `,
 	}
 
@@ -236,7 +242,7 @@ func listReleases(cmd *Command, args *Args) {
 		})
 		utils.Check(err)
 
-		colorize := ui.IsTerminal(os.Stdout)
+		colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 		for _, release := range releases {
 			flagReleaseFormat := "%T%n"
 			if args.Flag.HasReceived("--format") {
@@ -331,7 +337,7 @@ func showRelease(cmd *Command, args *Args) {
 
 		body := strings.TrimSpace(release.Body)
 
-		colorize := ui.IsTerminal(os.Stdout)
+		colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
 		if flagShowReleaseFormat := args.Flag.Value("--format"); flagShowReleaseFormat != "" {
 			ui.Print(formatRelease(*release, flagShowReleaseFormat, colorize))
 			return

commands/sync.go

@@ -2,7 +2,6 @@ package commands
 
 import (
 	"fmt"
-	"os"
 	"regexp"
 	"strings"
 
@@ -14,7 +13,7 @@ import (
 
 var cmdSync = &Command{
 	Run:   sync,
-	Usage: "sync",
+	Usage: "sync [--color]",
 	Long: `Fetch git objects from upstream and update local branches.
 
 - If the local branch is outdated, fast-forward it;
@@ -24,6 +23,11 @@ var cmdSync = &Command{
 If a local branch does not have any upstream configuration, but has a
 same-named branch on the remote, treat that as its upstream branch.
 
+## Options:
+	--color[=<WHEN>]
+		Enable colored output even if stdout is not a terminal. <WHEN> can be one
+		of "always" (default for '--color'), "never", or "auto" (default).
+
 ## See also:
 
 hub(1), git-fetch(1)
@@ -71,7 +75,8 @@ func sync(cmd *Command, args *Args) {
 		lightRed,
 		resetColor string
 
-	if ui.IsTerminal(os.Stdout) {
+	colorize := colorizeOutput(args.Flag.HasReceived("--color"), args.Flag.Value("--color"))
+	if colorize {
 		green = "\033[32m"
 		lightGreen = "\033[32;1m"
 		red = "\033[31m"

utils/args_parser.go

@@ -192,12 +192,12 @@ func NewArgsParser() *ArgsParser {
 
 func NewArgsParserWithUsage(usage string) *ArgsParser {
 	p := NewArgsParser()
-	f := `(-[a-zA-Z0-9@^]|--[a-z][a-z0-9-]+)(?:[ =]([a-zA-Z_<>:=-]+))?`
+	f := `(-[a-zA-Z0-9@^]|--[a-z][a-z0-9-]+)(?:\[?[ =]([a-zA-Z_<>:=-]+\]?))?`
 	re := regexp.MustCompile(fmt.Sprintf(`(?m)^\s*%s(?:,\s*%s)?$`, f, f))
 	for _, match := range re.FindAllStringSubmatch(usage, -1) {
 		n1 := match[1]
 		n2 := match[3]
-		hasValue := match[2] != "" || match[4] != ""
+		hasValue := !(match[2] == "" || strings.HasSuffix(match[2], "]")) || match[4] != ""
 		var aliases []string
 		if len(n1) == 2 && len(n2) > 2 {
 			aliases = []string{n1}

utils/args_parser_test.go

@@ -91,8 +91,9 @@ func TestArgsParser_Values(t *testing.T) {
 func TestArgsParser_Bool(t *testing.T) {
 	p := NewArgsParser()
 	p.RegisterBool("--noop")
+	p.RegisterBool("--color")
 	p.RegisterBool("--draft", "-d")
-	args := []string{"-d", "--draft=false"}
+	args := []string{"-d", "--draft=false", "--color=auto"}
 	rest, err := p.Parse(args)
 	equal(t, nil, err)
 	equal(t, []string{}, rest)
@@ -101,6 +102,8 @@ func TestArgsParser_Bool(t *testing.T) {
 	equal(t, false, p.HasReceived("-d"))
 	equal(t, false, p.HasReceived("--noop"))
 	equal(t, false, p.Bool("--noop"))
+	equal(t, true, p.HasReceived("--color"))
+	equal(t, "auto", p.Value("--color"))
 }
 
 func TestArgsParser_BoolValue(t *testing.T) {