Synopsis

git remote [-v]
git remote add <name> <url>
git remote remove <name>
git remote set-url <name> <url>

Description

The git remote command manages the set of repositories ("remotes") whose URLs are stored in your local config. Each remote has a short nickname (commonly origin for the original clone source and upstream for the project you forked from). When you run git fetch origin, git push origin, or similar, the nickname is resolved to the URL.

Remotes are stored in .git/config and can have separate URLs for fetching and pushing. They also carry refspecs that determine which refs to fetch and into what local namespace. Modern workflows often have only origin, while open-source contributors typically have both origin (their fork) and upstream (the canonical project).

In day-to-day use, git remote integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git remote --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git remote interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git remote's side effects helps avoid all three.

Common Options

Examples

git remote -v
# List all remotes with URLs

git remote add upstream https://github.com/original/project.git
# Add the upstream repo of a fork

git remote set-url origin [email protected]:me/project.git
# Switch from HTTPS to SSH

git remote prune origin
# Remove tracking branches that no longer exist on origin

Common Mistakes

Adding the wrong URL (typo, missing .git suffix on some hosts) leads to confusing fetch errors. Run git remote -v to confirm. After repository renames or fork ownership changes, your remote URLs become stale — fix them with set-url. Don't forget to git remote prune periodically to clean up branches deleted on the server.

Related Commands

git fetch, git push, git pull, git ls-remote