Generating Shell Completion Scripts with `gh completion` (with examples)

Display the subcommand help

To display the help for the gh completion command, you can simply run the following code:

gh completion

Motivation: By displaying the help for the gh completion command, you can get information about how to generate shell completion scripts for GitHub CLI commands.

Explanation: Running gh completion without any arguments will display the subcommand help and provide an overview of using the command.

Example Output: Running gh completion will display the subcommand help output:

Generate shell completion scripts for GitHub CLI commands.
More information: <https://cli.github.com/manual/gh_completion>.

USAGE
  $ gh completion

OPTIONS
  -h, --help  show CLI help

Print a completion script

To print a completion script for a specific shell, you need to provide the --shell option followed by the desired shell name. Here’s an example:

gh completion --shell bash

Motivation: Printing a completion script allows you to integrate GitHub CLI commands with your shell’s auto-completion functionality, making it easier to use and remember commands.

Explanation: By providing the --shell option, followed by the shell name (e.g., bash, zsh, fish, or powershell), the gh completion command will generate a completion script specific to that shell.

Example Output: Running gh completion --shell bash will print the completion script for the Bash shell:

# bash completion for gh

_gh_completion() {
    local curr_word words cword prev_word gh_alias

    if type gh >/dev/null 2>&1; then
        if hash gh 2>/dev/null; then
            gh_alias=$(alias | awk -F'[ =]' '{print $2" " $3}' | awk '/^gh=/ {print $1}')
            if [ -n "$gh_alias" ]; then
                eval "$gh_alias __complete $COMP_LINE"
                return $?
            else
                curr_word="${COMP_WORDS[COMP_CWORD]}"
                prev_word="${COMP_WORDS[COMP_CWORD-1]}"
                cword="$COMP_CWORD words=(${COMP_WORDS[*]:1})"
                words=("${(@f)$(gh __complete $cword -- "$COMP_LINE")}")
                COMPREPLY=()
                __ltrim_colon_completions "$prev_word"
                COMPREPLY=(${(j: :)"${(@)words[%CURRENT]}:Q}" "${words[@]//[^[:alnum:]-]/\\$MATCH"})
                __ltrim_colon_completions "$curr_word"
                return 0
            fi
        fi
    fi

    __gh_debug "cannot find 'gh' in PATH"
    return 1
}

complete -o default -F _gh_completion gh

Append the gh completion script to ~/.bashrc

To append the gh completion script to ~/.bashrc (the Bash resource file), you can use the following code:

gh completion --shell bash >> ~/.bashrc

Motivation: Appending the completion script to ~/.bashrc ensures that every new Bash session will have the GitHub CLI commands autocompletion enabled.

Explanation: By using the output redirection operator >>, the gh completion command will print the completion script for the Bash shell and append it to the ~/.bashrc file.

Example Output: Running gh completion --shell bash >> ~/.bashrc will append the Bash completion script for GitHub CLI commands to the ~/.bashrc file.

(Note: The output will not be visible, but the content will be appended to the file.)

Append the gh completion script to ~/.zshrc

To append the gh completion script to ~/.zshrc (the Zsh resource file), you can use the following code:

gh completion --shell zsh >> ~/.zshrc

Motivation: Appending the completion script to ~/.zshrc ensures that every new Zsh session will have the GitHub CLI commands autocompletion enabled.

Explanation: By using the output redirection operator >>, the gh completion command will print the completion script for the Zsh shell and append it to the ~/.zshrc file.

Example Output: Running gh completion --shell zsh >> ~/.zshrc will append the Zsh completion script for GitHub CLI commands to the ~/.zshrc file.

(Note: The output will not be visible, but the content will be appended to the file.)