gh-reference

Display a markdown reference of all gh commands

$ gh reference

gh help reference

<branch_name>
    Refers to a specific Git branch (e.g., main, feature-X) within the context of the repository.

<tag_name>
    Refers to a specific Git tag (e.g., v1.0.0, release-candidate) in the repository.

#<PR_number>
    Refers to a GitHub Pull Request by its number (e.g., #123). gh interprets this as a reference to the PR's merge commit or head branch, depending on the specific command's context.

<SHA>
    Refers to a specific commit by its full or partial SHA hash (e.g., abcdef1, 1234567890abcdef).

<owner>/<repo>[#<PR_number>]
    Refers to a pull request in a different GitHub repository (e.g., cli/cli#123).

HEAD, MERGE_HEAD, ORIG_HEAD
    Standard Git symbolic references pointing to the current commit, the commit being merged, or the previous HEAD, respectively.

The gh help reference topic provides detailed information on how the GitHub CLI (gh) interprets various types of Git and GitHub references when used as arguments in gh commands. This comprehensive guide covers understanding branch names, tag names, pull request numbers, commit SHAs, and special Git pointers like HEAD. It clarifies the precise syntax for specifying these references, explains how ambiguous references are resolved by the CLI, and outlines the precedence rules applied during resolution. This help topic is absolutely crucial for users who need to precisely target specific commits, branches, tags, or pull requests across different gh commands, ensuring accurate and intended operations and avoiding potential misinterpretations of arguments.

The term gh-reference is not a standalone executable command. It directly refers to the reference help topic within the GitHub CLI (gh) utility, accessed via the command gh help reference. This help topic itself does not accept command-line parameters; instead, it provides documentation on the various types of references that gh commands expect as arguments for their own operations.

The gh help reference documentation details the specific order and logic gh employs to resolve potentially ambiguous reference strings provided as arguments. This typically involves checking for exact matches first, then partial matches, and prioritizing local branches, remote branches, and tags in a defined sequence. Understanding this resolution logic is vital to prevent unintended operations, especially when providing abbreviated or potentially ambiguous references to gh commands, ensuring the correct Git object is targeted.

The reference help topic is an integral part of the GitHub CLI (gh) project. The gh CLI was first publicly released in beta in 2020. As the CLI matured and its command set expanded to cover more GitHub features, the necessity for clear and comprehensive documentation on how it handles various Git and GitHub-specific references became paramount. This help topic has evolved to cover the expanding forms of references supported by gh commands, ensuring users can accurately interact with their repositories.

gh(1), git(1), git-revisions(7)