list the various alias permutations for the command and subcommands, via '--help' and 'gh reference'

internal/docs/docs_test.go

@@ -28,6 +28,8 @@ func init() {
 
 	jsonCmd.Flags().StringSlice("json", nil, "help message for flag json")
 
+	aliasCmd.Flags().StringSlice("yang", nil, "help message for flag yang")
+
 	echoCmd.AddCommand(timesCmd, echoSubCmd, deprecatedCmd)
 	rootCmd.AddCommand(printCmd, echoCmd, dummyCmd)
 }
@@ -75,6 +77,13 @@ var printCmd = &cobra.Command{
 	Long:  `an absolutely utterly useless command for testing.`,
 }
 
+var aliasCmd = &cobra.Command{
+	Use:     "ying [yang]",
+	Short:   "The ying and yang of it all",
+	Long:    "an absolutely utterly useless command for testing aliases!.",
+	Aliases: []string{"yoo", "foo"},
+}
+
 var jsonCmd = &cobra.Command{
 	Use:   "blah --json <fields>",
 	Short: "View details in JSON",

internal/docs/man.go

@@ -179,6 +179,14 @@ func manPrintOptions(buf *bytes.Buffer, command *cobra.Command) {
 	}
 }
 
+func manPrintAliases(buf *bytes.Buffer, command *cobra.Command) {
+	if len(command.Aliases) > 0 {
+		buf.WriteString("# ALIASES\n")
+		buf.WriteString(strings.Join(root.BuildAliasList(command, command.Aliases), ", "))
+		buf.WriteString("\n")
+	}
+}
+
 func manPrintJSONFields(buf *bytes.Buffer, command *cobra.Command) {
 	raw, ok := command.Annotations["help:json-fields"]
 	if !ok {
@@ -207,6 +215,7 @@ func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
 		}
 	}
 	manPrintOptions(buf, cmd)
+	manPrintAliases(buf, cmd)
 	manPrintJSONFields(buf, cmd)
 	if len(cmd.Example) > 0 {
 		buf.WriteString("# EXAMPLE\n")

internal/docs/man_test.go

@@ -98,6 +98,21 @@ func TestGenManSeeAlso(t *testing.T) {
 	}
 }
 
+func TestGenManAliases(t *testing.T) {
+	buf := new(bytes.Buffer)
+	header := &GenManHeader{}
+	if err := renderMan(aliasCmd, header, buf); err != nil {
+		t.Fatal(err)
+	}
+
+	output := buf.String()
+
+	checkStringContains(t, output, translate(aliasCmd.Name()))
+	checkStringContains(t, output, "ALIASES")
+	checkStringContains(t, output, "foo")
+	checkStringContains(t, output, "yoo")
+}
+
 func TestGenManJSONFields(t *testing.T) {
 	buf := new(bytes.Buffer)
 	header := &GenManHeader{}

internal/docs/markdown.go

@@ -26,6 +26,15 @@ func printJSONFields(w io.Writer, cmd *cobra.Command) {
 	fmt.Fprint(w, "\n\n")
 }
 
+func printAliases(w io.Writer, cmd *cobra.Command) {
+	if len(cmd.Aliases) > 0 {
+		fmt.Fprintf(w, "### ALIASES\n\n")
+		fmt.Fprint(w, text.FormatSlice(strings.Split(strings.Join(root.BuildAliasList(cmd, cmd.Aliases), ", "), ","), 0, 0, "", "", true))
+		fmt.Fprint(w, "\n\n")
+	}
+
+}
+
 func printOptions(w io.Writer, cmd *cobra.Command) error {
 	flags := cmd.NonInheritedFlags()
 	flags.SetOutput(w)
@@ -147,6 +156,7 @@ func genMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 	if err := printOptions(w, cmd); err != nil {
 		return err
 	}
+	printAliases(w, cmd)
 	printJSONFields(w, cmd)
 	fmt.Fprint(w, "{% endraw %}\n")
 

internal/docs/markdown_test.go

@@ -70,6 +70,20 @@ func TestGenMdNoHiddenParents(t *testing.T) {
 	checkStringOmits(t, output, "Options inherited from parent commands")
 }
 
+func TestGenMdAliases(t *testing.T) {
+	buf := new(bytes.Buffer)
+	if err := genMarkdownCustom(aliasCmd, buf, nil); err != nil {
+		t.Fatal(err)
+	}
+	output := buf.String()
+
+	checkStringContains(t, output, aliasCmd.Long)
+	checkStringContains(t, output, jsonCmd.Example)
+	checkStringContains(t, output, "ALIASES")
+	checkStringContains(t, output, "yoo")
+	checkStringContains(t, output, "foo")
+}
+
 func TestGenMdJSONFields(t *testing.T) {
 	buf := new(bytes.Buffer)
 	if err := genMarkdownCustom(jsonCmd, buf, nil); err != nil {

pkg/cmd/root/help.go

@@ -132,7 +132,7 @@ func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, args []string) {
 	helpEntries = append(helpEntries, helpEntry{"USAGE", command.UseLine()})
 
 	if len(command.Aliases) > 0 {
-		helpEntries = append(helpEntries, helpEntry{"ALIASES", strings.Join(command.Aliases, "\n")})
+		helpEntries = append(helpEntries, helpEntry{"ALIASES", strings.Join(BuildAliasList(command, command.Aliases), ", ") + "\n"})
 	}
 
 	for _, g := range GroupedCommands(command) {
@@ -302,3 +302,24 @@ func dedent(s string) string {
 	}
 	return strings.TrimSuffix(buf.String(), "\n")
 }
+
+func BuildAliasList(cmd *cobra.Command, aliases []string) []string {
+	if !cmd.HasParent() {
+		return aliases
+	}
+
+	parentAliases := append(cmd.Parent().Aliases, cmd.Parent().Name())
+	sort.Strings(parentAliases)
+
+	var aliasesWithParentAliases []string
+	// e.g aliases = [ls]
+	for _, alias := range aliases {
+		// e.g parentAliases = [codespaces, cs]
+		for _, parentAlias := range parentAliases {
+			// e.g. aliasesWithParentAliases = [codespaces list, codespaces ls, cs list, cs ls]
+			aliasesWithParentAliases = append(aliasesWithParentAliases, fmt.Sprintf("%s %s", parentAlias, alias))
+		}
+	}
+
+	return BuildAliasList(cmd.Parent(), aliasesWithParentAliases)
+}

pkg/cmd/root/help_reference.go

@@ -62,6 +62,12 @@ func cmdRef(w io.Writer, cmd *cobra.Command, depth int) {
 		fmt.Fprintf(w, "```\n%s````\n\n", dedent(flagUsages))
 	}
 
+	// Aliases
+	if len(cmd.Aliases) > 0 {
+		fmt.Fprintf(w, "%s\n\n", "Aliases")
+		fmt.Fprintf(w, "\n%s\n\n", dedent(strings.Join(BuildAliasList(cmd, cmd.Aliases), ", ")))
+	}
+
 	// Subcommands
 	for _, c := range cmd.Commands() {
 		if c.Hidden {