LinuxCommandLibrary

gh-alias

Create shortcuts for GitHub CLI commands

TLDR

List all the aliases gh is configured to use

$ gh alias list
copy

Create a gh subcommand alias
$ gh alias set [pv] '[pr view]'
copy

Set a shell command as a gh subcommand
$ gh alias set [[-s|--shell]] [alias_name] [command]
copy

Delete a command shortcut
$ gh alias delete [alias_name]
copy

Display the subcommand help
$ gh alias
copy

SYNOPSIS

gh alias <command> [<args>...]

PARAMETERS

set
    Creates or updates an alias.
Usage: gh alias set <alias>=<expansion>

delete
    Deletes one or more aliases.
Usage: gh alias delete <alias>...

list
    Lists all currently configured aliases.
Usage: gh alias list

import
    Imports aliases from a file.
Usage: gh alias import [-i <file>]

export
    Exports aliases to a file.
Usage: gh alias export [-o <file>]

DESCRIPTION

The gh-alias command is a powerful utility within the GitHub CLI (
gh) that enables users to create, manage, and delete custom shortcuts (aliases) for frequently used
gh commands or complex command sequences.

By defining aliases, users can significantly reduce typing,
streamline their workflow, and personalize their command-line experience.
It supports setting simple command replacements,
as well as more advanced aliases that include flags or even pipe outputs to other commands.
Aliases can be listed, imported from, and exported to files,
facilitating easy sharing and backup of configurations.
This functionality is crucial for power users who want to optimize
their interaction with GitHub directly from the terminal.

CAVEATS

Aliases defined with gh alias are specific to the GitHub CLI and do not affect shell-level aliases (e.g., bash or zsh aliases).
Alias expansions are processed before any global flags, which can sometimes lead to unexpected behavior if not carefully considered.
Ensure alias names do not conflict with existing gh subcommands to avoid shadowing.

ALIAS EXPANSION LOGIC

Aliases can expand to full gh commands, including flags and arguments.
For example, gh alias set 'prview="gh pr view --web"' creates an alias that opens a pull request in the browser.
Complex expansions involving pipes or multiple commands can be achieved by quoting the expansion properly.

INTERACTIVE ALIASES

Aliases can be designed to prompt for input, allowing for dynamic command execution.
For instance, an alias could prompt for an issue number before opening it.
This leverages the underlying gh command's interactive capabilities.

HISTORY

The gh alias command was introduced as a core feature of the GitHub CLI
(gh) from its early development stages,
reflecting the design philosophy to provide a highly customizable and efficient command-line experience for GitHub users.
Its inclusion was crucial for enabling users to extend and personalize the CLI's capabilities
beyond its default set of commands, mirroring similar alias functionalities found in traditional shells.
It has evolved alongside the gh CLI, with ongoing refinements to its parsing and execution logic.

SEE ALSO

gh(1), alias(1), unalias(1), zsh(1), bash(1)

Copied to clipboard