LinuxCommandLibrary

gh-repo

Manage GitHub repositories from the command line

TLDR

Create a new repository (if the repository name is not set, the default name will be the name of the current directory)

$ gh repo create [name]
copy

Clone a repository
$ gh repo clone [owner]/[repository]
copy

Fork and clone a repository
$ gh repo fork [owner]/[repository] --clone
copy

View a repository in the default web browser
$ gh repo view [repository] [[-w|--web]]
copy

List repositories owned by a specific user or organization (if the owner is not set, the default owner will be the currently logged in user)
$ gh repo list [owner]
copy

List only non-forks repositories and limit the number of repositories to list (default: 30)
$ gh repo list [owner] --source [[-L|--limit]] [limit]
copy

List repositories with a specific primary coding language
$ gh repo list [owner] [[-l|--language]] [language_name]
copy

SYNOPSIS

gh repo command [flags]

Common commands include:
archive <repository>
clone <repository> [directory]
create [name]
delete <repository>
fork [repository]
list
rename <repository> <new-name>
sync [repository]
view [repository]

PARAMETERS

archive
    Archives a GitHub repository, making it read-only and preventing further commits.

clone
    Clones a GitHub repository to your local machine, creating a local Git repository.

create
    Creates a new GitHub repository, with options for visibility (public/private), description, and more.

delete
    Deletes a GitHub repository. This action is irreversible and requires explicit confirmation.

fork
    Forks a GitHub repository, creating a personal copy under your user or organization account.

list
    Lists repositories owned by or accessible to the authenticated GitHub user, with filtering options.

rename
    Renames an existing GitHub repository to a new specified name.

sync
    Synchronizes a forked GitHub repository with its upstream counterpart, updating local and remote branches.

view
    Views details of a GitHub repository, either by opening it in a web browser or printing its metadata.

--help
    Displays help information for the gh repo command or a specific subcommand.

--hostname host
    Specifies the GitHub host to interact with (e.g., github.com or a GitHub Enterprise instance).

--repo owner/repo
    Specifies the target repository for commands that operate on a specific repository but don't take it as a positional argument.

DESCRIPTION

The gh repo command is a powerful subcommand of the GitHub CLI (gh) that allows users to perform various repository management tasks directly from their terminal. It streamlines workflows by providing functions to create, clone, list, view, delete, archive, fork, rename, and synchronize GitHub repositories without needing to visit the web interface. This significantly enhances productivity for developers working with GitHub. Each specific action is handled by a subcommand, such as gh repo create or gh repo clone, making common operations quick and efficient and bringing the power of GitHub.com directly to your shell.

CAVEATS

The gh repo command relies on the GitHub CLI (gh) being installed and properly authenticated with your GitHub account (via gh auth login). All operations are performed against the GitHub API and are thus subject to network connectivity, API rate limits, and the user's permissions on the target repository. Deleting a repository is a permanent and irreversible action.

AUTHENTICATION REQUIREMENT

To use gh repo effectively, you must first authenticate your GitHub CLI session. This is typically done using the gh auth login command, which provides a user-friendly browser-based authentication flow. This step grants gh the necessary API tokens to interact with your GitHub repositories on your behalf.

REMOTE OPERATIONS FOCUS

It's important to distinguish that most gh repo operations primarily interact with the remote GitHub repository (e.g., on GitHub.com or your Enterprise instance). While gh repo clone initiates a local Git clone, subsequent commands like gh repo delete, gh repo archive, or gh repo rename modify the repository directly on GitHub's servers, not just your local copy.

HISTORY

The gh repo functionalities are core components of the GitHub CLI, which was initially released as a public beta in 2019 and reached its 1.0 milestone in 2020. Developed by GitHub, the CLI was designed to bring the essential features of the GitHub web interface directly to the command line, aiming to enhance developer productivity and streamline workflows. Repository management capabilities, including creating, cloning, and viewing repositories, were fundamental to the CLI's initial design and have been continuously refined since its inception.

SEE ALSO

gh(1), git(1), ssh(1)

Copied to clipboard