gh-reference

Display a markdown reference of all gh commands

$ gh reference

gh ref <command> [<flags>] <args>
where command is create|delete|list|view

--all, -a
    Include refs not associated with branches or tags (for list)

--limit <int>
    Maximum number of refs to list (default 30, for list)

--pattern <string>
    Pattern to match ref names (for list)

--pointed <string>
    Only refs pointing to given ref (for list)

--branch <string>
    Branch the ref points to (for create)

--tag <string>
    Tag the ref points to (for create)

<name>
    Ref name (required for create, delete, view)

--json
    Output as JSON (for list, view)

--jq <expr>, -q
    JMESPath filter for JSON (for list, view)

--repo <OWNER/REPO>
    Target specific repository

--remote <string>
    Infer repo from remote (alternative to --repo)

The gh ref command is part of the GitHub CLI toolset, enabling users to manage Git references such as branches and tags directly from the terminal. It interacts with the GitHub API to list, create, delete, or view refs in a repository, bypassing the need for full git clones or web UI navigation.

Primary use cases include automation in CI/CD pipelines, bulk ref management, and scripting repository maintenance. For instance, list all branches with gh ref list, create a lightweight tag with gh ref create mytag --tag v1.0, or delete unused refs programmatically.

Unlike native git commands, gh ref operates remotely on GitHub without local repo modifications, making it ideal for hosted repo administration. It supports filtering, pagination, and JSON output for integration with other tools. Authentication via gh auth login is required, and access levels determine permissions (e.g., write for create/delete).

Subcommands provide targeted functionality: list for discovery, create for new refs, delete for cleanup, and view for inspection. Flags like --repo allow targeting specific repositories, enhancing flexibility in monorepo or org-wide workflows.

Requires GitHub CLI installed and authenticated (gh auth login). Limited to refs visible to user; no direct commit creation. Use git for local ops.

gh ref list --limit 10
gh ref create feat-branch --branch main
gh ref delete old-tag
gh ref view HEAD --json

GitHub account with repo access. Install via brew install gh or similar.

Introduced in GitHub CLI v0.11.0 (October 2020) for basic ref listing. Enhanced with create/delete in v1.0 (2021), JSON/JQ support in v2.0+, aligning with GitHub API v3 evolution.

gh(1), git-branch(1), git-tag(1), git(1)