Documentation for built-in aliases (like 'cs' for 'codespace') #8315

Activity

1. josefpihrt

   added

   enhancementa request to improve CLIa request to improve CLI

   on Nov 9, 2023
2. cliAutomation

   added

   needs-triageneeds to be reviewedneeds to be reviewed

   on Nov 9, 2023
3. andyfeller commented on Nov 9, 2023

   

   andyfeller

   on Nov 9, 2023

   Contributor

   More actions

   @josefpihrt : Very good question.

   What other commands are aliased?

   There are many: https://github.com/search?q=repo%3Acli%2Fcli+%22Aliases%3A+%5B%5Dstring%22&type=code

   What is the underlying problem?

   Under the covers, we use spf13/cobra for all of the command line argument and flag handling as well as usage generation. By default, spf13/cobra will output aliases in usage, however the GitHub CLI has overridden this logic:

   cli/pkg/cmd/root/help.go

   Lines 90 to 190 in ebcf3a1

   	func rootHelpFunc(f *cmdutil.Factory, command *cobra.Command, args []string) {
   	flags := command.Flags()
   	if isRootCmd(command) {
   	if versionVal, err := flags.GetBool("version"); err == nil && versionVal {
   	fmt.Fprint(f.IOStreams.Out, command.Annotations["versionInfo"])
   	return
   	} else if err != nil {
   	fmt.Fprintln(f.IOStreams.ErrOut, err)
   	hasFailed = true
   	return
   	}
   	}
   	cs := f.IOStreams.ColorScheme()
   	if help, _ := flags.GetBool("help"); !help && !command.Runnable() && len(flags.Args()) > 0 {
   	nestedSuggestFunc(f.IOStreams.ErrOut, command, flags.Args()[0])
   	hasFailed = true
   	return
   	}
   	namePadding := 12
   	type helpEntry struct {
   	Title string
   	Body string
   	}
   	longText := command.Long
   	if longText == "" {
   	longText = command.Short
   	}
   	if longText != "" && command.LocalFlags().Lookup("jq") != nil {
   	longText = strings.TrimRight(longText, "\n") +
   	"\n\nFor more information about output formatting flags, see `gh help formatting`."
   	}
   	helpEntries := []helpEntry{}
   	if longText != "" {
   	helpEntries = append(helpEntries, helpEntry{"", longText})
   	}
   	helpEntries = append(helpEntries, helpEntry{"USAGE", command.UseLine()})
   	for _, g := range GroupedCommands(command) {
   	var names []string
   	for _, c := range g.Commands {
   	names = append(names, rpad(c.Name()+":", namePadding)+c.Short)
   	}
   	helpEntries = append(helpEntries, helpEntry{
   	Title: strings.ToUpper(g.Title),
   	Body: strings.Join(names, "\n"),
   	})
   	}
   	if isRootCmd(command) {
   	var helpTopics []string
   	if c := findCommand(command, "actions"); c != nil {
   	helpTopics = append(helpTopics, rpad(c.Name()+":", namePadding)+c.Short)
   	}
   	for _, helpTopic := range HelpTopics {
   	helpTopics = append(helpTopics, rpad(helpTopic.name+":", namePadding)+helpTopic.short)
   	}
   	sort.Strings(helpTopics)
   	helpEntries = append(helpEntries, helpEntry{"HELP TOPICS", strings.Join(helpTopics, "\n")})
   	}
   	flagUsages := command.LocalFlags().FlagUsages()
   	if flagUsages != "" {
   	helpEntries = append(helpEntries, helpEntry{"FLAGS", dedent(flagUsages)})
   	}
   	inheritedFlagUsages := command.InheritedFlags().FlagUsages()
   	if inheritedFlagUsages != "" {
   	helpEntries = append(helpEntries, helpEntry{"INHERITED FLAGS", dedent(inheritedFlagUsages)})
   	}
   	if _, ok := command.Annotations["help:arguments"]; ok {
   	helpEntries = append(helpEntries, helpEntry{"ARGUMENTS", command.Annotations["help:arguments"]})
   	}
   	if command.Example != "" {
   	helpEntries = append(helpEntries, helpEntry{"EXAMPLES", command.Example})
   	}
   	if _, ok := command.Annotations["help:environment"]; ok {
   	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.
   	Read the manual at https://cli.github.com/manual`})
   	out := f.IOStreams.Out
   	for _, e := range helpEntries {
   	if e.Title != "" {
   	// If there is a title, add indentation to each line in the body
   	fmt.Fprintln(out, cs.Bold(e.Title))
   	fmt.Fprintln(out, text.Indent(strings.Trim(e.Body, "\r\n"), " "))
   	} else {
   	// If there is no title print the body as is
   	fmt.Fprintln(out, e.Body)
   	}
   	fmt.Fprintln(out)
   	}
   	}

   If I'm interpreting the code correctly, spf13/cobra will delegate put the parent/child command structure for how to output usage if there isn't a customized override in place. This means the logic for the root command help might need to be enhanced to include aliases.
4. samcoe commented on Nov 13, 2023

   

   samcoe

   on Nov 13, 2023

   Contributor

   More actions

   @josefpihrt This is a good point. The default aliases are not documented anywhere. I would like to see us expand the help doc text for each command to include any known aliases. Additionally, I think we could update the gh reference command to include showing aliases.

   ❤️React with ❤️1Reacted by Andy Feller
5. samcoe

   added

   docs

   help wantedContributions welcomeContributions welcome

   and removed

   needs-triageneeds to be reviewedneeds to be reviewed

   on Nov 13, 2023
6. andyfeller

   added

   discussFeature changes that require discussion primarily among the GitHub CLI teamFeature changes that require discussion primarily among the GitHub CLI team

   on Dec 4, 2023
7. andyfeller

   closed this as completedin #8367on Feb 8, 2024