How to Use the Command 'gh completion' (with examples)

The gh completion command is a part of the GitHub CLI, or gh, which provides a comprehensive and intuitive way to interact with GitHub directly from your terminal. This command primarily generates shell completion scripts for the GitHub CLI commands. Shell completions are scripts that enable your shell to auto-complete commands and their arguments, significantly enhancing the efficiency and speed of command-line operations. By using these scripts, developers can save time and reduce the cognitive load needed to remember a plethora of command syntaxes, especially useful if you’re dealing with multiple CLI tools on a regular basis.

Use case 1: Print a completion script

Code:

gh completion --shell bash|zsh|fish|powershell

Motivation:

The primary reason for using this command is to generate a shell-specific completion script without immediately applying changes to your shell configuration files. It is particularly useful for inspecting the script before execution, ensuring it aligns with your system’s requisites or understanding how the completion logic is structured, which could be educational for those learning about shell scripting and command-line environments.

Explanation:

• gh: Invokes the GitHub CLI.
• completion: Tells the tool that we want to work with command completion features.
• --shell: Specifies the shell for which you want to generate a completion script. This argument is crucial because completion scripts are specific to the type of shell you’re using (e.g., bash, zsh, fish, or powershell).

Example Output:

Executing the code will output a shell-specific script, formatted and ready to be added to your shell configuration, like a new function or completion rules.

Use case 2: Append the gh completion script to ~/.bashrc

Code:

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

Motivation:

Appending the output directly to your .bashrc file allows for persistent integration of the completion script whenever a new terminal session is started with Bash. This removes the need to manually source or paste it every time, resulting in an automated and seamless user experience. This approach is advantageous if you frequently use the GitHub CLI and prefer having the completions ready without further configurations.

Explanation:

• >> ~/.bashrc: This redirects the output of the command and appends it to the .bashrc file located in the user’s home directory. .bashrc is a script that runs every time a new terminal session begins in Bash, automating setup tasks, including our command completions.

Example Output:

No immediate output is displayed in the terminal since the command appends the script to the .bashrc file. After restarting or sourcing the terminal, you’ll notice that you can now utilize autocompletion for gh commands.

Use case 3: Append the gh completion script to ~/.zshrc

Code:

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

Motivation:

Much like the previous example, this command integrates gh command completions into your Zsh shell environment. For users of the zsh shell, appending the completion script to .zshrc ensures that they benefit from command completions every time a new terminal instance of zsh is opened. This setup means increased productivity, as completion suggestions for gh commands will automatically be available.

Explanation:

• >> ~/.zshrc: Appends the generated completion script to the .zshrc file in your home directory. .zshrc is the run-control file for zsh initialization, and placing completion scripts here allows for persistence across terminal sessions.

Example Output:

While this specific command won’t produce visible terminal output immediately, once you start a new zsh session, the completions are enabled, facilitating efficient command-line interactions.

Use case 4: Display the subcommand help

Code:

gh completion

Motivation:

This command serves as a helpful tool for users needing more information about how to use the gh completion functionality effectively. By aiming to discover additional options or get a refresher on arguments available, this command aligns well with users seeking to extend their understanding of gh capabilities.

Explanation:

• The command simply calls gh completion. Running it without arguments displays help information related to gh completion, elucidating possible options and their uses, thus acting as a quick reference guide.

Example Output:

The output of this command provides detailed help information, outlining the possible --shell options, as well as contextual usage scenarios, enabling users to receive immediate assistance directly from the terminal.

Conclusion

The gh completion command for the GitHub CLI is a powerful aid for those frequently operating within a terminal environment. Through various use cases such as generating, appending, and understanding shell-specific completion scripts, users can enhance their workflow significantly. These scripts simplify typing, prevent errors from incorrect syntax, and streamline frequent usage of GitHub CLI commands, proving to be invaluable in bolstering productivity and efficiency for developers.