Skip to content

Commit fb7fdc3

Browse files
probablycoreyprobablycorey
authored
Merge pull request cli#1106 from cli/h-e-l-p
Style all commands like the root help command
2 parents 13b5c46 + 2fb48e9 commit fb7fdc3

File tree

5 files changed

+174
-114
lines changed

5 files changed

+174
-114
lines changed

‎command/help.go‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
package command
2+
3+
import (
4+
"fmt"
5+
"strings"
6+
7+
"github.com/cli/cli/utils"
8+
"github.com/spf13/cobra"
9+
)
10+
11+
func rootHelpFunc(command *cobra.Command, args []string) {
12+
// Display helpful error message in case subcommand name was mistyped.
13+
// This matches Cobra's behavior for root command, which Cobra
14+
// confusingly doesn't apply to nested commands.
15+
if command != RootCmd {
16+
if command.Parent() == RootCmd && len(args) >= 2 {
17+
if command.SuggestionsMinimumDistance <= 0 {
18+
command.SuggestionsMinimumDistance = 2
19+
}
20+
candidates := command.SuggestionsFor(args[1])
21+
22+
errOut := command.OutOrStderr()
23+
fmt.Fprintf(errOut, "unknown command %q for %q\n", args[1], "gh "+args[0])
24+
25+
if len(candidates) > 0 {
26+
fmt.Fprint(errOut, "\nDid you mean this?\n")
27+
for _, c := range candidates {
28+
fmt.Fprintf(errOut, "\t%s\n", c)
29+
}
30+
fmt.Fprint(errOut, "\n")
31+
}
32+
33+
oldOut := command.OutOrStdout()
34+
command.SetOut(errOut)
35+
defer command.SetOut(oldOut)
36+
}
37+
}
38+
39+
coreCommands := []string{}
40+
additionalCommands := []string{}
41+
for _, c := range command.Commands() {
42+
if c.Short == "" {
43+
continue
44+
}
45+
if c.Hidden {
46+
continue
47+
}
48+
49+
s := rpad(c.Name()+":", c.NamePadding()) + c.Short
50+
if _, ok := c.Annotations["IsCore"]; ok {
51+
coreCommands = append(coreCommands, s)
52+
} else {
53+
additionalCommands = append(additionalCommands, s)
54+
}
55+
}
56+
57+
// If there are no core commands, assume everything is a core command
58+
if len(coreCommands) == 0 {
59+
coreCommands = additionalCommands
60+
additionalCommands = []string{}
61+
}
62+
63+
type helpEntry struct {
64+
Title string
65+
Body string
66+
}
67+
68+
helpEntries := []helpEntry{}
69+
if command.Long != "" {
70+
helpEntries = append(helpEntries, helpEntry{"", command.Long})
71+
} else if command.Short != "" {
72+
helpEntries = append(helpEntries, helpEntry{"", command.Short})
73+
}
74+
helpEntries = append(helpEntries, helpEntry{"USAGE", command.UseLine()})
75+
if len(coreCommands) > 0 {
76+
helpEntries = append(helpEntries, helpEntry{"CORE COMMANDS", strings.Join(coreCommands, "\n")})
77+
}
78+
if len(additionalCommands) > 0 {
79+
helpEntries = append(helpEntries, helpEntry{"ADDITIONAL COMMANDS", strings.Join(additionalCommands, "\n")})
80+
}
81+
if command.HasLocalFlags() {
82+
helpEntries = append(helpEntries, helpEntry{"FLAGS", strings.TrimRight(command.LocalFlags().FlagUsages(), "\n")})
83+
}
84+
if _, ok := command.Annotations["help:arguments"]; ok {
85+
helpEntries = append(helpEntries, helpEntry{"ARGUMENTS", command.Annotations["help:arguments"]})
86+
}
87+
if command.Example != "" {
88+
helpEntries = append(helpEntries, helpEntry{"EXAMPLES", command.Example})
89+
}
90+
helpEntries = append(helpEntries, helpEntry{"LEARN MORE", `
91+
Use "gh <command> <subcommand> --help" for more information about a command.
92+
Read the manual at http://cli.github.com/manual`})
93+
if _, ok := command.Annotations["help:feedback"]; ok {
94+
helpEntries = append(helpEntries, helpEntry{"FEEDBACK", command.Annotations["help:feedback"]})
95+
}
96+
97+
out := colorableOut(command)
98+
for _, e := range helpEntries {
99+
if e.Title != "" {
100+
// If there is a title, add indentation to each line in the body
101+
fmt.Fprintln(out, utils.Bold(e.Title))
102+
103+
for _, l := range strings.Split(strings.Trim(e.Body, "\n\r"), "\n") {
104+
l = strings.Trim(l, " \n\r")
105+
fmt.Fprintln(out, " "+l)
106+
}
107+
} else {
108+
// If there is no title print the body as is
109+
fmt.Fprintln(out, e.Body)
110+
}
111+
fmt.Fprintln(out)
112+
}
113+
}
114+
115+
// rpad adds padding to the right of a string.
116+
func rpad(s string, padding int) string {
117+
template := fmt.Sprintf("%%-%ds ", padding)
118+
return fmt.Sprintf(template, s)
119+
}

‎command/issue.go‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,17 @@ func init() {
4949
}
5050

5151
var issueCmd = &cobra.Command{
52-
Use: "issue",
52+
Use: "issue <command>",
5353
Short: "Create and view issues",
54-
Long: `Work with GitHub issues.
55-
56-
An issue can be supplied as argument in any of the following formats:
54+
Long: `Work with GitHub issues`,
55+
Example: `$ gh issue list
56+
$ gh issue create --fill
57+
$ gh issue view --web`,
58+
Annotations: map[string]string{
59+
"IsCore": "true",
60+
"help:arguments": `An issue can be supplied as argument in any of the following formats:
5761
- by number, e.g. "123"; or
58-
- by URL, e.g. "https://github.com/OWNER/REPO/issues/123".`,
62+
- by URL, e.g. "https://github.com/OWNER/REPO/issues/123".`},
5963
}
6064
var issueCreateCmd = &cobra.Command{
6165
Use: "create",

‎command/pr.go‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,19 +46,27 @@ func init() {
4646
}
4747

4848
var prCmd = &cobra.Command{
49-
Use: "pr",
49+
Use: "pr <command>",
5050
Short: "Create, view, and checkout pull requests",
51-
Long: `Work with GitHub pull requests.
52-
53-
A pull request can be supplied as argument in any of the following formats:
51+
Long: `Work with GitHub pull requests`,
52+
Example: `$ gh pr checkout 353
53+
$ gh pr checkout bug-fix-branch
54+
$ gh pr create --fill
55+
$ gh pr view --web`,
56+
Annotations: map[string]string{
57+
"IsCore": "true",
58+
"help:arguments": `A pull request can be supplied as argument in any of the following formats:
5459
- by number, e.g. "123";
5560
- by URL, e.g. "https://github.com/OWNER/REPO/pull/123"; or
56-
- by the name of its head branch, e.g. "patch-1" or "OWNER:patch-1".`,
61+
- by the name of its head branch, e.g. "patch-1" or "OWNER:patch-1".`},
5762
}
5863
var prListCmd = &cobra.Command{
5964
Use: "list",
6065
Short: "List and filter pull requests in this repository",
61-
RunE: prList,
66+
Example: `$ gh pr list --limit all
67+
$ gh pr list --state closed
68+
$ gh pr list --label “priority 1” “bug”`,
69+
RunE: prList,
6270
}
6371
var prStatusCmd = &cobra.Command{
6472
Use: "status",

‎command/repo.go‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,13 +44,19 @@ func init() {
4444
}
4545

4646
var repoCmd = &cobra.Command{
47-
Use: "repo",
47+
Use: "repo <command>",
4848
Short: "Create, clone, fork, and view repositories",
49-
Long: `Work with GitHub repositories.
50-
49+
Long: `Work with GitHub repositories`,
50+
Example: `$ gh repo create
51+
$ gh repo clone cli/cli
52+
$ gh repo view --web
53+
`,
54+
Annotations: map[string]string{
55+
"IsCore": "true",
56+
"help:arguments": `
5157
A repository can be supplied as an argument in any of the following formats:
5258
- "OWNER/REPO"
53-
- by URL, e.g. "https://github.com/OWNER/REPO"`,
59+
- by URL, e.g. "https://github.com/OWNER/REPO"`},
5460
}
5561

5662
var repoCloneCmd = &cobra.Command{
@@ -69,9 +75,18 @@ To pass 'git clone' flags, separate them with '--'.`,
6975
var repoCreateCmd = &cobra.Command{
7076
Use: "create [<name>]",
7177
Short: "Create a new repository",
72-
Long: `Create a new GitHub repository.
73-
74-
Use the "ORG/NAME" syntax to create a repository within your organization.`,
78+
Long: `Create a new GitHub repository`,
79+
Example: utils.Bold("$ gh repo create") + `
80+
Will create a repository on your account using the name of your current directory
81+
82+
` + utils.Bold("$ gh repo create my-project") + `
83+
Will create a repository on your account using the name 'my-project'
84+
85+
` + utils.Bold("$ gh repo create cli/my-project") + `
86+
Will create a repository in the organization 'cli' using the name 'my-project'`,
87+
Annotations: map[string]string{"help:arguments": `A repository can be supplied as an argument in any of the following formats:
88+
- <OWNER/REPO>
89+
- by URL, e.g. "https://github.com/OWNER/REPO"`},
7590
RunE: repoCreate,
7691
}
7792

‎command/root.go‎

Lines changed: 10 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ var Version = "DEV"
3434
var BuildDate = "" // YYYY-MM-DD
3535

3636
var versionOutput = ""
37-
var cobraDefaultHelpFunc func(*cobra.Command, []string)
3837

3938
func init() {
4039
if Version == "DEV" {
@@ -58,9 +57,11 @@ func init() {
5857
// TODO:
5958
// RootCmd.PersistentFlags().BoolP("verbose", "V", false, "enable verbose output")
6059

61-
cobraDefaultHelpFunc = RootCmd.HelpFunc()
6260
RootCmd.SetHelpFunc(rootHelpFunc)
6361

62+
// This will silence the usage func on error
63+
RootCmd.SetUsageFunc(func(_ *cobra.Command) error { return nil })
64+
6465
RootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
6566
if err == pflag.ErrHelp {
6667
return err
@@ -95,6 +96,13 @@ var RootCmd = &cobra.Command{
9596

9697
SilenceErrors: true,
9798
SilenceUsage: true,
99+
Example: `$ gh issue create
100+
$ gh repo clone
101+
$ gh pr checkout 321`,
102+
Annotations: map[string]string{
103+
"help:feedback": `
104+
Fill out our feedback form https://forms.gle/umxd3h31c7aMQFKG7
105+
Open an issue using “gh issue create -R cli/cli”`},
98106
}
99107

100108
var versionCmd = &cobra.Command{
@@ -320,100 +328,6 @@ func determineBaseRepo(apiClient *api.Client, cmd *cobra.Command, ctx context.Co
320328
return baseRepo, nil
321329
}
322330

323-
func rootHelpFunc(command *cobra.Command, args []string) {
324-
if command != RootCmd {
325-
// Display helpful error message in case subcommand name was mistyped.
326-
// This matches Cobra's behavior for root command, which Cobra
327-
// confusingly doesn't apply to nested commands.
328-
if command.Parent() == RootCmd && len(args) >= 2 {
329-
if command.SuggestionsMinimumDistance <= 0 {
330-
command.SuggestionsMinimumDistance = 2
331-
}
332-
candidates := command.SuggestionsFor(args[1])
333-
334-
errOut := command.OutOrStderr()
335-
fmt.Fprintf(errOut, "unknown command %q for %q\n", args[1], "gh "+args[0])
336-
337-
if len(candidates) > 0 {
338-
fmt.Fprint(errOut, "\nDid you mean this?\n")
339-
for _, c := range candidates {
340-
fmt.Fprintf(errOut, "\t%s\n", c)
341-
}
342-
fmt.Fprint(errOut, "\n")
343-
}
344-
345-
oldOut := command.OutOrStdout()
346-
command.SetOut(errOut)
347-
defer command.SetOut(oldOut)
348-
}
349-
cobraDefaultHelpFunc(command, args)
350-
return
351-
}
352-
353-
type helpEntry struct {
354-
Title string
355-
Body string
356-
}
357-
358-
coreCommandNames := []string{"issue", "pr", "repo"}
359-
var coreCommands []string
360-
var additionalCommands []string
361-
for _, c := range command.Commands() {
362-
if c.Short == "" {
363-
continue
364-
}
365-
s := " " + rpad(c.Name()+":", c.NamePadding()) + c.Short
366-
if includes(coreCommandNames, c.Name()) {
367-
coreCommands = append(coreCommands, s)
368-
} else if !c.Hidden {
369-
additionalCommands = append(additionalCommands, s)
370-
}
371-
}
372-
373-
helpEntries := []helpEntry{
374-
{
375-
"",
376-
command.Long},
377-
{"USAGE", command.Use},
378-
{"CORE COMMANDS", strings.Join(coreCommands, "\n")},
379-
{"ADDITIONAL COMMANDS", strings.Join(additionalCommands, "\n")},
380-
{"FLAGS", strings.TrimRight(command.LocalFlags().FlagUsages(), "\n")},
381-
{"EXAMPLES", `
382-
$ gh issue create
383-
$ gh repo clone
384-
$ gh pr checkout 321`},
385-
{"LEARN MORE", `
386-
Use "gh <command> <subcommand> --help" for more information about a command.
387-
Read the manual at http://cli.github.com/manual`},
388-
{"FEEDBACK", `
389-
Fill out our feedback form https://forms.gle/umxd3h31c7aMQFKG7
390-
Open an issue using “gh issue create -R cli/cli”`},
391-
}
392-
393-
out := colorableOut(command)
394-
for _, e := range helpEntries {
395-
if e.Title != "" {
396-
fmt.Fprintln(out, utils.Bold(e.Title))
397-
}
398-
fmt.Fprintln(out, strings.TrimLeft(e.Body, "\n")+"\n")
399-
}
400-
}
401-
402-
// rpad adds padding to the right of a string.
403-
func rpad(s string, padding int) string {
404-
template := fmt.Sprintf("%%-%ds ", padding)
405-
return fmt.Sprintf(template, s)
406-
}
407-
408-
func includes(a []string, s string) bool {
409-
for _, x := range a {
410-
if x == s {
411-
return true
412-
}
413-
}
414-
return false
415-
}
416-
417331
func formatRemoteURL(cmd *cobra.Command, fullRepoName string) string {
418332
ctx := contextForCommand(cmd)
419333

0 commit comments

Comments
 (0)