git remote

Add, rename, prune, set URLs.

🎯 What & why

git remote manages the named URLs your repo talks to. Without it, fetch and push have nowhere to go.

🧠 Mental model

A remote is just a named bookmark to another repo's URL plus a refspec. origin is convention, not magic — you can have as many remotes as you want, each with its own fetch/push URL.

🛠️ Synopsis

git remote [-v]
git remote add [-t <branch>] [--mirror=fetch|push] <name> <url>
git remote rename <old> <new>
git remote remove <name>
git remote set-url [--push] <name> <newurl>
git remote show <name>
git remote prune <name>

🎚️ Switches & options

Flag	What it does
`-v / --verbose`	Show URLs alongside names. Use this always — bare `git remote` is nearly useless.
`--track <branch>`	On `add`, restrict the fetch refspec to one branch instead of all.
`--mirror=fetch`	Fetch maps refs exactly — including remote-tracking and tags. Useful for backup mirrors.
`--mirror=push`	⚠️ Push deletes refs on the remote that don't exist locally. Destructive — only for true mirrors.
`-f`	On `add`, fetch immediately after adding. Saves a step.
`--no-tags / --tags`	On `add`, control whether tag auto-following happens.

📦 Subcommands

add — Register a new remote.

git remote add upstream https://github.com/torvalds/linux.git

rename — Rename a remote (also rewrites local config refspecs).

git remote rename origin github

remove / rm — Forget a remote and its tracking refs.

git remote remove old-fork

set-url — Change a remote's URL. --push sets only the push URL.

git remote set-url origin git@github.com:me/repo.git

set-head — Set or auto-detect the remote's default branch.

git remote set-head origin --auto

show — Verbose dump: URLs, tracked branches, stale refs.

git remote show origin

prune — Delete local remote-tracking refs that no longer exist upstream.

git remote prune origin

update — Fetch from one or all remotes.

git remote update --prune

get-url — Print the URL. Scriptable; cleaner than parsing -v.

git remote get-url --push origin

💡 Use cases

Forking workflow: origin is your fork, upstream is the canonical repo.
Migrating a repo to a new host without losing history (set-url, then push).
Mirroring: --mirror=push to a backup server on a cron.
Cleaning up after upstream branch deletions with prune.

🧪 Examples

Add an upstream for a fork

git remote add upstream https://github.com/owner/repo.git

Switch from HTTPS to SSH

git remote set-url origin git@github.com:owner/repo.git

Inspect everything about a remote

git remote show origin

Fetch all remotes and clean stale refs

git remote update --prune

🎓 Recommendations

Use origin for your fork and upstream for the source. Don't invent novel naming — readers expect this.
Run git remote prune origin (or set fetch.prune=true) to keep git branch -r honest.
Prefer SSH URLs for write access; HTTPS only when you genuinely need it (corporate proxies, CI tokens).

🪤 Common pitfalls

--mirror=push will delete remote branches that don't exist locally. People lose work this way.
set-url does not update the push URL unless you pass --push. Triple-URL setups confuse everyone.
Renaming a remote rewrites refspecs in .git/config; custom refspecs you hand-edited may not survive cleanly.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.