Documentation for built-in aliases

[Rebeccasun31]

Fixes #8315

I tried to fix this issue by adding "ALIASES" entry in help doc text for each commands.
Please check it out if it meets your needs.
Thank you!

[andyfeller]

@Rebeccasun31 : thank you for taking a first pass at fixing this! ❤️ Checking out your changes and running it locally, I'm not sure this is exactly what we need. 🤔

As you can see, my gh alias entries are listed here rather than the aliases of the native / core commands:

andyfeller@Andrews-MacBook-Pro:cli/cli ‹show_aliases›$ go build cmd/gh/main.go                                                          

andyfeller@Andrews-MacBook-Pro:cli/cli ‹show_aliases*›$ ./main --help
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  ...

GITHUB ACTIONS COMMANDS
  ...

EXTENSION COMMANDS
  ...

ALIAS COMMANDS
  co:          Alias for "pr checkout"
  explain:     Alias for "copilot-internal explain"
  suggest-gh:  Alias for "copilot-internal suggest -t gh"
  suggest-git: Alias for "copilot-internal suggest -t git"
  suggest-shell: Alias for "copilot-internal suggest -t shell"


andyfeller@Andrews-MacBook-Pro:cli/cli ‹show_aliases*›$ gh alias list
co: pr checkout
explain: copilot-internal explain
suggest-gh: copilot-internal suggest -t gh
suggest-git: copilot-internal suggest -t git
suggest-shell: copilot-internal suggest -t shell

How might we fix this?

I think we need to pull the children commands of the current command and build the entries based off the aliases for each command, remembering that a command can have multiple aliases.

What do you think?

[Rebeccasun31]

@andyfeller: thanks for your reply! Before adding more changes, I want to clarify some concepts.

I think we need to list all built-in aliases for each command, so I add a new ALIASES entry in help doc.

• For example, the gh codespace command mentioned in the issue will have a new documentation like this:

  C:\Users\Rebecca Sun\Desktop\cli>go run script/build.go
  
  
  C:\Users\Rebecca Sun\Desktop\cli>bin\gh codespace --help
  Connect to and manage codespaces
  
  USAGE
    gh codespace [flags]
  
  ALIASES
    cs
  
  AVAILABLE COMMANDS
    ...
  
  INHERITED FLAGS
    ...
  

• For its child command gh codespace list, there is also an ALIASES entry:

  C:\Users\Rebecca Sun\Desktop\cli>bin\gh codespace list --help
  List codespaces of the authenticated user.
  
  Alternatively, organization administrators may list all codespaces billed to the organization.
  
  For more information about output formatting flags, see `gh help formatting`.
  
  USAGE
    gh codespace list [flags]
  
  ALIASES
    ls
  
  FLAGS
    ...
  
  INHERITED FLAGS
    ...
  

However, if we just type gh --help, the following documentation is for the root command, so the ALIAS COMMANDS will list all the gh alias entries which are not the built-in aliases:

C:\Users\Rebecca Sun\Desktop\cli>bin\gh --help          
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  ...

GITHUB ACTIONS COMMANDS
  ...

ALIAS COMMANDS
  co:          Alias for "pr checkout"


C:\Users\Rebecca Sun\Desktop\cli>bin\gh alias list       
co: pr checkout

My Questions

1. Should I list all the built-in aliases in gh --help?
2. Are the gh alias entries also needed to be listed in the help doc for each command if they exist?

If there's something unclarity, please let me know. Thank you!

[andyfeller]

@Rebeccasun31 : excellent summarization!

1. Should I list all the built-in aliases in gh --help?

Personally, I think that would make an already long usage / help documentation even longer.

I think your examples of generating help for specific commands or subcommands other than root is right sized 👌

gh --help as of v2.40.0

Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  auth:        Authenticate gh and git with GitHub
  browse:      Open the repository in the browser
  codespace:   Connect to and manage codespaces
  gist:        Manage gists
  issue:       Manage issues
  org:         Manage organizations
  pr:          Manage pull requests
  project:     Work with GitHub Projects.
  release:     Manage releases
  repo:        Manage repositories

GITHUB ACTIONS COMMANDS
  cache:       Manage Github Actions caches
  run:         View details about workflow runs
  workflow:    View details about GitHub Actions workflows

EXTENSION COMMANDS
  actions-importer: Extension actions-importer
  ado2gh:      Extension ado2gh
  classroom-private: Extension classroom-private
  codeowner-analysis: Extension codeowner-analysis
  copilot:     Extension copilot
  copilot-internal: Extension copilot-internal
  dependency-report: Extension dependency-report
  gei:         Extension gei
  kraken:      Extension kraken
  migrate-project: Extension migrate-project
  montage:     Extension montage
  nonsense:    Extension nonsense
  nonsense-internal: Extension nonsense-internal
  projects:    Extension projects
  publicize:   Extension publicize
  repo-explore: Extension repo-explore
  repo-export: Extension repo-export
  repo-stats:  Extension repo-stats
  slack:       Extension slack
  ssh-allowed-signers: Extension ssh-allowed-signers
  token:       Extension token
  webhook:     Extension webhook

ALIAS COMMANDS
  co:          Alias for "pr checkout"
  explain:     Alias for "copilot-internal explain"
  suggest-gh:  Alias for "copilot-internal suggest -t gh"
  suggest-git: Alias for "copilot-internal suggest -t git"
  suggest-shell: Alias for "copilot-internal suggest -t shell"

ADDITIONAL COMMANDS
  alias:       Create command shortcuts
  api:         Make an authenticated GitHub API request
  completion:  Generate shell completion scripts
  config:      Manage configuration for gh
  extension:   Manage gh extensions
  gpg-key:     Manage GPG keys
  label:       Manage labels
  ruleset:     View info about repo rulesets
  search:      Search for repositories, issues, and pull requests
  secret:      Manage GitHub secrets
  ssh-key:     Manage SSH keys
  status:      Print information about relevant issues, pull requests, and notifications across repositories
  variable:    Manage GitHub Actions variables

HELP TOPICS
  actions:     Learn about working with GitHub Actions
  environment: Environment variables that can be used with gh
  exit-codes:  Exit codes used by gh
  formatting:  Formatting options for JSON data exported from gh
  mintty:      Information about using gh with MinTTY
  reference:   A comprehensive reference of all gh commands

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

2. Are the gh alias entries also needed to be listed in the help doc for each command if they exist?

Personally, I don't think so. My initial thought was that custom gh alias wouldn't show up no more than what extensions you have installed, however I realized that both show up in gh --help already:

EXTENSION COMMANDS
  actions-importer: Extension actions-importer
  ado2gh:      Extension ado2gh
  classroom-private: Extension classroom-private
  codeowner-analysis: Extension codeowner-analysis
  copilot:     Extension copilot
  copilot-internal: Extension copilot-internal
  dependency-report: Extension dependency-report
  gei:         Extension gei
  kraken:      Extension kraken
  migrate-project: Extension migrate-project
  montage:     Extension montage
  nonsense:    Extension nonsense
  nonsense-internal: Extension nonsense-internal
  projects:    Extension projects
  publicize:   Extension publicize
  repo-explore: Extension repo-explore
  repo-export: Extension repo-export
  repo-stats:  Extension repo-stats
  slack:       Extension slack
  ssh-allowed-signers: Extension ssh-allowed-signers
  token:       Extension token
  webhook:     Extension webhook

ALIAS COMMANDS
  co:          Alias for "pr checkout"
  explain:     Alias for "copilot-internal explain"
  suggest-gh:  Alias for "copilot-internal suggest -t gh"
  suggest-git: Alias for "copilot-internal suggest -t git"
  suggest-shell: Alias for "copilot-internal suggest -t shell"

Figuring out how to correlate gh alias entries to the native commands involved and how to deal with multiple native commands or whatever would be a pain.

Hope that makes sense

[Rebeccasun31]

@andyfeller: sorry for the late reply ! ><
Since I am really willing to solve this issue, I would like to make sure I haven't misunderstood and left any detail behind.

Based on my understanding, you want only the built-in alias but not the self-defined alias to appear in the --help text. The adjustments we made in commands and sub-commands have so far met your need except for the "gh" command. Therefore, if I want to continue working on and finally solve this issue, my goal would be to properly deal with the "gh" root command.

Is this what you were hoping for?

If yes, and if you are worrying that listing all built-in aliases in "gh --help" would too much extend the context, how about removing the "ALIAS COMMANDS" section in "gh --help"?

Since the current "ALIAS COMMANDS" section in "gh --help" doesn't really list out all the built-in aliases, and you don't want the custom aliases to show up, I am wondering that the current "ALIAS COMMANDS" section in "gh --help" might become somehow weird, for the meaning represented by the current "ALIAS COMMANDS" section in "gh --help" is somewhat different from that of the others.

What do you think about it? :)

[andyfeller]

@andyfeller: sorry for the late reply ! ><

@Rebeccasun31 : I have to equally beg your forgiveness as recovering from holiday downtime and new year priorities has made catching up a bit difficult, so thank you for your patience and diligence in supporting the GitHub CLI! 🤗

Based on my understanding, you want only the built-in alias but not the self-defined alias to appear in the --help text. The adjustments we made in commands and sub-commands have so far met your need except for the "gh" command. Therefore, if I want to continue working on and finally solve this issue, my goal would be to properly deal with the "gh" root command.

Is this what you were hoping for?

I will admit now looking back on my comment if I was getting these changes confused in my mind. As you say, you're adding the ALIASES section for the individual commands and the root help already shows the custom aliases you have defined. Trying to add more to the root usage output would be unwieldy, so let me re-review this and see how we get this shipped.

Output from gh --help from PR

Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  auth:        Authenticate gh and git with GitHub
  browse:      Open the repository in the browser
  codespace:   Connect to and manage codespaces
  gist:        Manage gists
  issue:       Manage issues
  org:         Manage organizations
  pr:          Manage pull requests
  project:     Work with GitHub Projects.
  release:     Manage releases
  repo:        Manage repositories

GITHUB ACTIONS COMMANDS
  cache:       Manage Github Actions caches
  run:         View details about workflow runs
  workflow:    View details about GitHub Actions workflows

EXTENSION COMMANDS
  actions-importer: Extension actions-importer
  ado2gh:      Extension ado2gh
  catsup:      Extension catsup
  classroom-private: Extension classroom-private
  codeowner-analysis: Extension codeowner-analysis
  copilot:     Extension copilot
  copilot-internal: Extension copilot-internal
  dependency-report: Extension dependency-report
  gei:         Extension gei
  kraken:      Extension kraken
  migrate-project: Extension migrate-project
  montage:     Extension montage
  nonsense:    Extension nonsense
  nonsense-internal: Extension nonsense-internal
  projects:    Extension projects
  publicize:   Extension publicize
  repo-explore: Extension repo-explore
  repo-export: Extension repo-export
  repo-stats:  Extension repo-stats
  slack:       Extension slack
  ssh-allowed-signers: Extension ssh-allowed-signers
  token:       Extension token
  webhook:     Extension webhook

ALIAS COMMANDS
  co:          Alias for "pr checkout"
  explain:     Alias for "copilot-internal explain"
  suggest-gh:  Alias for "copilot-internal suggest -t gh"
  suggest-git: Alias for "copilot-internal suggest -t git"
  suggest-shell: Alias for "copilot-internal suggest -t shell"

ADDITIONAL COMMANDS
  alias:       Create command shortcuts
  api:         Make an authenticated GitHub API request
  completion:  Generate shell completion scripts
  config:      Manage configuration for gh
  extension:   Manage gh extensions
  gpg-key:     Manage GPG keys
  label:       Manage labels
  ruleset:     View info about repo rulesets
  search:      Search for repositories, issues, and pull requests
  secret:      Manage GitHub secrets
  ssh-key:     Manage SSH keys
  status:      Print information about relevant issues, pull requests, and notifications across repositories
  variable:    Manage GitHub Actions variables

HELP TOPICS
  actions:     Learn about working with GitHub Actions
  environment: Environment variables that can be used with gh
  exit-codes:  Exit codes used by gh
  formatting:  Formatting options for JSON data exported from gh
  mintty:      Information about using gh with MinTTY
  reference:   A comprehensive reference of all gh commands

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

Output from gh codespace --help from PR

$ ./bin/gh codespace --help
Connect to and manage codespaces

USAGE
  gh codespace [flags]

ALIASES
  cs

AVAILABLE COMMANDS
  code:        Open a codespace in Visual Studio Code
  cp:          Copy files between local and remote file systems
  create:      Create a codespace
  delete:      Delete codespaces
  edit:        Edit a codespace
  jupyter:     Open a codespace in JupyterLab
  list:        List codespaces
  logs:        Access codespace logs
  ports:       List ports in a codespace
  rebuild:     Rebuild a codespace
  ssh:         SSH into a codespace
  stop:        Stop a running codespace
  view:        View details about a codespace

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

Once again, my sincerest apologies for the confusion and delay! 🙇

[andyfeller]

@Rebeccasun31 : What are your thoughts about enhancing gh reference to also include native aliases?

cli/pkg/cmd/root/help_reference.go

Lines 43 to 72 in b8c4ea1

	func stringifyReference(cmd *cobra.Command) string {
	buf := bytes.NewBufferString("# gh reference\n\n")
	for _, c := range cmd.Commands() {
	if c.Hidden {
	continue
	}
	cmdRef(buf, c, 2)
	}
	return buf.String()
	}
	func cmdRef(w io.Writer, cmd *cobra.Command, depth int) {
	// Name + Description
	fmt.Fprintf(w, "%s `%s`\n\n", strings.Repeat("#", depth), cmd.UseLine())
	fmt.Fprintf(w, "%s\n\n", cmd.Short)
	// Flags
	// TODO: fold in InheritedFlags/PersistentFlags, but omit `--help` due to repetitiveness
	if flagUsages := cmd.Flags().FlagUsages(); flagUsages != "" {
	fmt.Fprintf(w, "```\n%s````\n\n", dedent(flagUsages))
	}
	// Subcommands
	for _, c := range cmd.Commands() {
	if c.Hidden {
	continue
	}
	cmdRef(w, c, depth+1)
	}
	}

In general, I like @samcoe suggestion but realize it might be a little tricky because gh reference is alphabetized based on the command or subcommand name including user-created aliases. For example, gh codespace with an alias of cs would need an entry after several commands including gh codespace <subcommand>, gh completion, and gh config before an entry should show up. 🤔

## `gh codespace`

Connect to and manage codespaces

### `gh codespace code [flags]`

Open a codespace in Visual Studio Code

  -c, --codespace string    Name of the codespace
      --insiders            Use the insiders version of Visual Studio Code
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
  -w, --web                 Use the web version of Visual Studio Code

### `gh codespace cp [-e] [-r] [-- [<scp flags>...]] <sources>... <dest>`

Copy files between local and remote file systems

  -c, --codespace string    Name of the codespace
  -e, --expand              Expand remote file names on remote shell
  -p, --profile string      Name of the SSH profile to use
  -r, --recursive           Recursively copy directories
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)

### `gh codespace create [flags]`

Create a codespace

  -b, --branch string               repository branch
      --default-permissions         do not prompt to accept additional permissions requested by the codespace
      --devcontainer-path string    path to the devcontainer.json file to use when creating codespace
  -d, --display-name string         display name for the codespace
      --idle-timeout duration       allowed inactivity before codespace is stopped, e.g. "10m", "1h"
  -l, --location string             location: {EastUs|SouthEastAsia|WestEurope|WestUs2} (determined automatically if not provided)
  -m, --machine string              hardware specifications for the VM
  -R, --repo string                 repository name with owner: user/repo
      --retention-period duration   allowed time after shutting down before the codespace is automatically deleted (maximum 30 days), e.g. "1h", "72h"
  -s, --status                      show status of post-create command and dotfiles
  -w, --web                         create codespace from browser, cannot be used with --display-name, --idle-timeout, or --retention-period

### `gh codespace delete [flags]`

Delete codespaces

      --all                 Delete all codespaces
  -c, --codespace string    Name of the codespace
      --days N              Delete codespaces older than N days
  -f, --force               Skip confirmation for codespaces that contain unsaved changes
  -o, --org login           The login handle of the organization (admin-only)
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
  -u, --user username       The username to delete codespaces for (used with --org)

### `gh codespace edit [flags]`

Edit a codespace

  -c, --codespace string      Name of the codespace
  -d, --display-name string   Set the display name
  -m, --machine string        Set hardware specifications for the VM
  -R, --repo string           Filter codespace selection by repository name (user/repo)
      --repo-owner string     Filter codespace selection by repository owner (username or org)

### `gh codespace jupyter [flags]`

Open a codespace in JupyterLab

  -c, --codespace string    Name of the codespace
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)

### `gh codespace list [flags]`

List codespaces

  -q, --jq expression     Filter JSON output using a jq expression
      --json fields       Output JSON with the specified fields
  -L, --limit int         Maximum number of codespaces to list (default 30)
  -o, --org login         The login handle of the organization to list codespaces for (admin-only)
  -R, --repo string       Repository name with owner: user/repo
  -t, --template string   Format JSON output using a Go template; see "gh help formatting"
  -u, --user username     The username to list codespaces for (used with --org)
  -w, --web               List codespaces in the web browser, cannot be used with --user or --org

### `gh codespace logs [flags]`

Access codespace logs

  -c, --codespace string    Name of the codespace
  -f, --follow              Tail and follow the logs
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)

### `gh codespace ports [flags]`

List ports in a codespace

  -c, --codespace string    Name of the codespace
  -q, --jq expression       Filter JSON output using a jq expression
      --json fields         Output JSON with the specified fields
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
  -t, --template string     Format JSON output using a Go template; see "gh help formatting"

#### `gh codespace ports forward <remote-port>:<local-port>...`

Forward ports

#### `gh codespace ports visibility <port>:{public|private|org}...`

Change the visibility of the forwarded port

### `gh codespace rebuild [flags]`

Rebuild a codespace

  -c, --codespace string    Name of the codespace
      --full                perform a full rebuild
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)

### `gh codespace ssh [<flags>...] [-- <ssh-flags>...] [<command>]`

SSH into a codespace

  -c, --codespace string    Name of the codespace
      --config              Write OpenSSH configuration to stdout
  -d, --debug               Log debug data to a file
      --debug-file string   Path of the file log to
      --profile string      Name of the SSH profile to use
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
      --server-port int     SSH server port number (0 => pick unused)

### `gh codespace stop [flags]`

Stop a running codespace

  -c, --codespace string    Name of the codespace
  -o, --org login           The login handle of the organization (admin-only)
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
  -u, --user username       The username to stop codespace for (used with --org)

### `gh codespace view [flags]`

View details about a codespace

  -c, --codespace string    Name of the codespace
  -q, --jq expression       Filter JSON output using a jq expression
      --json fields         Output JSON with the specified fields
  -R, --repo string         Filter codespace selection by repository name (user/repo)
      --repo-owner string   Filter codespace selection by repository owner (username or org)
  -t, --template string     Format JSON output using a Go template; see "gh help formatting"

The only other thing that comes to mind is we don't create an entry but include the information in the main command description before it goes onto subcommands:

## `gh codespace`

Connect to and manage codespaces

[andyfeller]

@Rebeccasun31 : not wanting to see your work stall further, I think we should proceed for now with a follow up for adding these aliases in gh reference. so, I'm going to re-review the changes and potentially merge them.

[andyfeller]

@Rebeccasun31 : Doing some manual testing on both command aliases and subcommand aliases, let's get these changes merged and follow up on a separate issue for adding aliases to gh reference

Manual testing

Command aliasing

andyfeller@Andrews-MBP cli % ./bin/gh codespace --help
Connect to and manage codespaces

USAGE
  gh codespace [flags]

ALIASES
  cs

AVAILABLE COMMANDS
  code:        Open a codespace in Visual Studio Code
  cp:          Copy files between local and remote file systems
  create:      Create a codespace
  delete:      Delete codespaces
  edit:        Edit a codespace
  jupyter:     Open a codespace in JupyterLab
  list:        List codespaces
  logs:        Access codespace logs
  ports:       List ports in a codespace
  rebuild:     Rebuild a codespace
  ssh:         SSH into a codespace
  stop:        Stop a running codespace
  view:        View details about a codespace

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual

Subcommand aliasing

andyfeller@Andrews-MBP cli % ./bin/gh codespace list --help
List codespaces of the authenticated user.

Alternatively, organization administrators may list all codespaces billed to the organization.

For more information about output formatting flags, see `gh help formatting`.

USAGE
  gh codespace list [flags]

ALIASES
  ls

FLAGS
  -q, --jq expression     Filter JSON output using a jq expression
      --json fields       Output JSON with the specified fields
  -L, --limit int         Maximum number of codespaces to list (default 30)
  -o, --org login         The login handle of the organization to list codespaces for (admin-only)
  -R, --repo string       Repository name with owner: user/repo
  -t, --template string   Format JSON output using a Go template; see "gh help formatting"
  -u, --user username     The username to list codespaces for (used with --org)
  -w, --web               List codespaces in the web browser, cannot be used with --user or --org

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual