Home / Alt manpages / gh-repo-set-default(1)

  • gh-repo-set-default(1)
  • User command
  • linux

Give gh a Default Repository for One Git Directory

A clone with two or three remotes leaves gh guessing which GitHub repository you mean, and gh repo set-default is how you stop the guessing. It stores your choice with the local Git repository, so later commands stop asking or picking the wrong one. Allow about ten minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • You need: GitHub CLI and an existing Git working tree with at least one remote you can access. The examples use gh 2.87.3, installed on this machine on 23 September 2026.

The command writes repository-local Git configuration. It does not need sudo and does not change files on GitHub.

1. Check the command before changing the repository

Run the version and help checks from the clone you intend to configure. They are read-only:

$ gh --version
gh version 2.87.3 (2026-02-23)

$ gh repo set-default --help
USAGE
  gh repo set-default [<repository>] [flags]

FLAGS
  -u, --unset   Unset the current default repository
  -v, --view    View the current default repository

The installed package's manpage describes the same command and two options. Treat the exact help from your own binary as the version-specific reference if your package is older or newer.

Checkpoint

Make sure the prompt is in the intended working tree. This reports its path without modifying anything:

$ git rev-parse --show-toplevel
/home/you/src/project

2. Inspect the remotes and choose the target

List the remotes before setting a default:

$ git remote -v
origin  [email protected]:ACME/widget.git (fetch)
origin  [email protected]:ACME/widget.git (push)
mirror  https://github.com/ACME/widget-mirror.git (fetch)
mirror  https://github.com/ACME/widget-mirror.git (push)
  • Use an owner and repository name such as ACME/widget for an unambiguous target.
  • Or pass a Git remote name, such as origin, when that remote resolves to the right GitHub repository. Do not assume origin is correct: forks, mirrors and release remotes commonly make that assumption wrong.

A repository argument is not a new clone and does not alter the remote URL. It tells gh which repository to use for GitHub API operations that otherwise infer a target from the local checkout.

3. Set the default explicitly

For a precise, script-friendly choice, pass the repository in OWNER/REPOSITORY form:

$ gh repo set-default ACME/widget
$ gh repo set-default --view
ACME/widget

The set operation is normally quiet, so the view command is your checkpoint: it should print the repository you intended. If it prints another repository, stop and investigate before creating an issue, pull request or release.

When the matching remote is already correct, the remote name is convenient:

$ gh repo set-default origin
$ gh repo set-default --view
ACME/widget

This selection follows the checkout, not every clone on the machine, so another working tree can have a different default. It is local metadata and is not included in a commit.

4. Use the default where it helps

The default repository is used by gh commands that query or act on a repository when you have not supplied another target:

$ gh pr list
$ gh issue list
$ gh release list
$ gh run list

These still need authentication and the permissions the operation requires. A default repository does not grant access and does not override an explicit repository argument. Before any write operation, confirm the target with gh repo set-default --view and check the command's own help for its target options.

Safety boundary

The installed gh help says the default repository is not used for managing repository and environment secrets. Do not infer a secret-management target from this setting; supply the repository explicitly when the relevant command supports that option.

5. Handle an ambiguous or invalid remote

If gh repo set-default REMOTE reports that none of the Git remotes correspond to a valid remote repository, check the remote URL and test the owner and repository spelling:

$ git remote get-url origin
[email protected]:ACME/widget.git
$ gh repo set-default ACME/widget
$ gh repo set-default --view
ACME/widget

A made-up placeholder such as example/project, a deleted repository or a remote on another Git host cannot become a valid GitHub default. Fixing a remote URL is a separate Git operation that can affect future fetches and pushes, so do not change it merely to silence this command. If the checkout is a fork or mirror, decide deliberately whether GitHub API queries should use that fork or the upstream repository.

Tip

Running gh repo set-default with no argument opens an interactive picker, useful when several remotes are valid. In a script or a repeatable setup note, use an explicit repository instead so the choice is visible and does not depend on terminal interaction.

6. Remove the local choice carefully

Unsetting is a local configuration change. It does not delete the repository, alter a remote, or remove anything from GitHub:

$ gh repo set-default --unset
$ gh repo set-default --view
X No default remote repository has been set. To learn more about the default repository, run: gh repo set-default --help

The exact diagnostic marker and wording can vary with the gh release; the useful result is that no repository name is shown as the current default. If your installed release starts an interactive prompt or rejects the option outside a terminal, use its own --help output and complete the removal interactively rather than editing Git configuration by guesswork.

Recovery

If you unset the wrong checkout's value, run gh repo set-default OWNER/REPOSITORY again from that checkout. If you need to recover after changing a remote URL, restore the previous URL with the normal git remote set-url workflow after checking it carefully. There is no elevated-privilege recovery step.

Done means

  • gh --version and gh repo set-default --help match the installed CLI.
  • You inspected the current directory and its remotes before choosing a target.
  • gh repo set-default --view prints the intended OWNER/REPOSITORY.
  • Repository-aware commands use the local default without changing the remote URL.
  • You know the default grants nothing: no permissions, no secrets access.
  • You can remove the setting with gh repo set-default --unset and restore it explicitly if needed.