Introduction

A remote is a named URL pointing to another Git repository. git clone creates one called origin automatically, but you can add as many as you like. Remotes are the bridge between your local repo and the outside world.

Listing and inspecting

git remote
git remote -v
git remote show origin

git remote show contacts the server and reports tracked branches, push rules, and stale refs.

Adding and removing

git remote add upstream https://github.com/original/widget.git
git remote rename upstream origin-upstream
git remote remove origin-upstream

The fork-and-upstream pattern is common: origin is your fork, upstream is the project you forked from.

Changing a URL

If a project moves from HTTPS to SSH or to a new host:

git remote set-url origin [email protected]:example/widget.git
git remote -v

Multiple URLs

You can push to several mirrors at once by adding extra push URLs:

git remote set-url --add --push origin [email protected]:example/widget.git
git remote -v

Pruning stale branches

When branches are deleted on the server, your local refs/remotes/origin/* can lag. Clean them:

git fetch --prune
git remote prune origin

Or set it permanently:

git config --global fetch.prune true

Inspecting tracking

git branch -vv
# main           a1b2c3d [origin/main] Latest fix
# feature/login  e4f5g6h [origin/feature/login: ahead 2] WIP

-vv shows each branch's upstream and how far ahead/behind it is.

insteadOf rewriting

If a project's URLs change (HTTPS to SSH, host migration, or you want all GitHub URLs to use SSH automatically), insteadOf rewrites them transparently:

git config --global url."[email protected]:".insteadOf "https://github.com/"
git config --global url."https://github-mirror.example.com/".insteadOf "https://github.com/"

This is especially handy in CI, where you can rewrite all clones to a local mirror with one config line, no script edits required. The reverse direction (pushInsteadOf) lets you fetch over HTTPS but push over SSH from the same remote.

Triangular workflows

In open source, you typically fetch from upstream (the canonical project) and push to origin (your personal fork). Configure once and forget:

git remote add upstream https://github.com/project/repo.git
git config branch.main.remote upstream
git config branch.main.pushRemote origin
git config --global push.default current

Now git pull reads from upstream and git push writes to your fork, automatically. The remote.pushDefault setting applies the rule to every branch in a clone.

Common mistakes

Confusing the name of a remote with its URL. origin is just a label; you can rename it. Another trap: adding the same URL under two different names, then being surprised by duplicate refs. Use git remote -v to audit. Forgetting to git fetch after switching network or changing URL leaves your tracking branches out of date. Finally, on shared servers, deleting a remote-tracking ref locally (e.g. git branch -dr origin/main) does not delete the branch on the server; use git push origin --delete main for that, and only when you really mean it.