Git Remote Explained: Add, Set-URL, Rename, Remove and Push URLs
git remote manages the named connections between your local repository and the servers you push to and pull from. Learn how origin works, adding and listing remotes, changing URLs, separate push URLs, working with forks and an upstream remote, renaming and removing, pruning stale branches, and the credentials leak to avoid, all run in a real repository.
- A remote is a named URL stored in your repository config;
originis just the default name used bygit clone. - git remote
addcreates a remote,set-urlchanges it,renameandremovemanage names. - A remote can have different fetch and push URLs, which
git remote -vshows separately. - Never put a token in a remote URL:
git remote -vprinted our fake token in plain text.
Every git push and git pull needs to know where to send or fetch commits. Typing a full server URL each time would be painful, so Git lets you save URLs under short names called remotes. The git remote command manages those names. It is simple, but changing a repository’s URL after a migration, working with a fork and its original, or cleaning up deleted branches all depend on understanding it.
We ran every command with Git 2.56, using local bare repositories as stand-in servers so nothing touched the internet, a placeholder identity (Demo, demo@example.com), and fixed dates. Output is copied from those runs. For branch basics, see our git branch guide.
What is a Git remote?
A remote is a bookmark: a name such as origin that maps to a repository URL, plus rules for which branches to fetch. Remotes live in .git/config:
git config --get remote.origin.url
../server.git
git config --get remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*
The fetch rule (a refspec) says: copy every branch on the server into a local read-only namespace refs/remotes/origin/. That is where remote-tracking branches such as origin/main come from. They are snapshots of the server, updated only when you fetch.
Our test setup
git init --bare server.git # stands in for GitHub or GitLab
git init --bare backup.git # a second server
git init -b main app # our working repository
Bare repositories have no working files and are exactly what Git servers store, so they behave like real remotes for push and fetch, without any network or account.
Listing remotes
git remote -v
(none yet)
git remote lists names; -v adds the fetch and push URL for each. A freshly initialised repository has none. A cloned repository starts with one called origin, pointing at where you cloned from.
Adding a remote
git remote add origin ../server.git
git remote -v
origin ../server.git (fetch)
origin ../server.git (push)
git remote add origin ../server.git
error: remote origin already exists.
git remote add <name> <url> saves a new remote. If the name is taken, Git refuses, the error many people hit when following setup instructions in a repository that already has origin. In that case you want set-url, not add.
First push and upstream tracking
git push -u origin main
git branch -vv
* main 06960ab [origin/main] Initial commit
-u (short for --set-upstream) pushes and records origin/main as the branch your local main tracks. From then on, plain git push and git pull know where to go, and git status reports how far ahead or behind you are.
Inspecting a remote
git remote show origin
* remote origin
Fetch URL: ../server.git
Push URL: ../server.git
HEAD branch: (unknown)
Remote branch:
main tracked
Local branch configured for 'git pull':
main merges with remote main
git remote show contacts the server and summarises URLs, remote branches, which local branches track them, and stale branches. It is the best single command when pushes go somewhere unexpected.
Changing a remote URL
git remote set-url origin ../backup.git
git remote -v
origin ../backup.git (fetch)
origin ../backup.git (push)
git remote set-url upstream ../x.git
error: No such remote 'upstream'
When a repository moves, from one host to another, a renamed organisation, or HTTPS to SSH, update the URL in place with set-url. Tracking configuration stays intact, so nothing else needs changing. It only works for existing names, as the second command shows.
A separate push URL
git remote set-url --push origin ../backup.git
git remote -v
origin ../server.git (fetch)
origin ../backup.git (push)
A remote can fetch from one URL and push to another. Uses include fetching over anonymous HTTPS but pushing over SSH, or pushing to a mirror. This is also why git remote -v prints two lines per remote. You can even add several push URLs with set-url --add --push, so one push updates two servers.
Working with forks: origin and upstream
git remote add upstream ../backup.git
git remote
origin
upstream
When you fork a project, origin is your fork and, by convention, upstream is the original project. You fetch new changes from upstream, merge or rebase them into your branches, and push to origin to open pull requests. Keeping both remotes makes syncing a fork a two-command job: git fetch upstream, then git rebase upstream/main.
Renaming and removing remotes
git remote rename upstream mirror
git branch -r
mirror/main
origin/main
git remote remove mirror
git branch -r
origin/main
rename updates the name and moves its remote-tracking branches, as mirror/main shows. remove (or rm) deletes the remote and all its remote-tracking branches from your local repository. It never deletes anything on the server.
Tip: git fetch --all updates every remote at once, handy when you work with both origin and upstream.
Pruning stale remote-tracking branches
When a teammate deletes a branch on the server, your origin/feature-x stays until you prune it. Run git fetch --prune (or git remote prune origin) to remove remote-tracking branches that no longer exist on the server. Set git config --global fetch.prune true to do it on every fetch. Pruning is safe: it only removes read-only snapshots, never your local branches.
HTTPS vs SSH remote URLs
| Format | Example | Authentication |
|---|---|---|
| HTTPS | https://github.com/org/repo.git |
Credential manager or personal access token |
| SSH | git@github.com:org/repo.git |
SSH key |
| Local path | ../server.git |
File permissions |
Switching between them is just git remote set-url origin <new-url>. SSH avoids typing tokens once your key is set up; see our SSH keys guide.
The credentials leak to avoid
git remote add leaky https://user:SECRET123@example.com/repo.git
git remote -v
leaky https://user:SECRET123@example.com/repo.git (fetch)
leaky https://user:SECRET123@example.com/repo.git (push)
Embedding a token in a remote URL stores it in plain text in .git/config, and Git prints it whenever anyone runs git remote -v, shares a screenshot or pastes CI logs. (The token above is fake.) Use a credential helper, an SSH key, or in CI a token injected from a secret store through environment variables. If a token has ever been in a URL, revoke it.
Git remote cheat sheet
| Task | Command |
|---|---|
| List remotes with URLs | git remote -v |
| Add a remote | git remote add origin <url> |
| Change a URL | git remote set-url origin <url> |
| Separate push URL | git remote set-url --push origin <url> |
| Inspect | git remote show origin |
| Rename | git remote rename old new |
| Remove | git remote remove name |
| Prune deleted branches | git fetch --prune |
| Push and track | git push -u origin main |
The wider command set is in our Git commands cheat sheet.
Pushing to two servers at once, and checking with ls-remote
git remote add origin ../origin.git
git remote set-url --add --push origin ../origin.git
git remote set-url --add --push origin ../mirror.git
git remote -v
# origin ../origin.git (fetch)
# origin ../origin.git (push)
# origin ../mirror.git (push)
git push origin main
git ls-remote origin
# a3d7d995c333... HEAD
# a3d7d995c333... refs/heads/main
git ls-remote ../mirror.git
# a3d7d995c333... refs/heads/main same commit on the mirror
A remote can have several push URLs, so one git push updates a main server and a backup mirror together. There is a trap here that we confirmed in a second repository: the moment you add any push URL, Git stops using the fetch URL for pushing. When we added only the mirror, the push went to the mirror and the original server received nothing. Add the original URL as a push URL first, then the extra one, exactly as above.
git ls-remote lists the branches and commits on a remote without fetching anything, which makes it a quick way to confirm that a push landed or that a URL works at all. git remote get-url --push --all origin prints every push URL, and with a second named remote added, git fetch --all updated both origin/main and mirror/main in one command. For automating mirror pushes in a pipeline, see our GitHub Actions CI/CD guide.
Final thoughts
git remote is the address book of your repository. Add origin once, use set-url when servers change, keep upstream alongside origin for forks, prune stale branches regularly, and keep credentials out of URLs. With those habits, pushing and pulling across any number of servers stays predictable. Automating pushes from CI is covered in our GitHub Actions guide.
Frequently asked questions
What is origin in Git?
origin is the default name Git gives to the remote you cloned from. It is just a name for a URL, and you can rename it or add other remotes.
How do I change the remote URL in Git?
Run git remote set-url origin followed by the new URL. Tracking branches and settings stay the same, so nothing else needs to change.
How do I fix remote origin already exists?
The repository already has a remote named origin. Use git remote set-url to change its URL, or add your new remote under a different name.
What is the difference between origin and upstream?
By convention origin is your own copy or fork, and upstream is the original project you forked from. You fetch from upstream and push to origin.
Does git remote remove delete the repository on the server?
No. It only removes the remote name and its remote-tracking branches from your local repository. The server repository is not touched.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.