git remote
Sharing and Updating
Manage the remote repositories you sync with
The 'git remote' command lists, adds and removes remotes — short names for the URLs of other repositories. git clone creates one called origin. Forks usually add a second one, upstream, pointing to the original project. Adding a remote downloads nothing; git fetch <name> does.
Synopsis
git remote [-v | --verbose]
git remote add <name> <url>
git remote remove <name>
git remote rename <old> <new>
git remote set-url <name> <newurl>
git remote show <name>[ ] optional| or<arg> placeholder... repeatable--flag option
Options
Choosing the Right Option
origin vs upstream
The two usual remotes of a fork
| Command | Points to | You push? |
|---|---|---|
origin | Your copy (the fork) | Yes |
upstream | The original project | No — you fetch from it |
Examples
List remotes
git remote -vNames with their URLs.
Add the original of a fork
git remote add upstream git@github.com:acme/shop.gitA second remote.
Change a URL
git remote set-url origin git@github.com:you/shop.gitE.g. switch from HTTPS to SSH.
Details
git remote show originBranches and tracking information.
Workflow Examples
1
git remote add upstream git@github.com:acme/shop.gitOnce
2
git fetch upstreamDownload its commits
3
git merge upstream/mainBring them into your main
4
git pushUpdate your fork
Troubleshooting
error: remote origin already exists
Cause: The name is taken
Use set-url to change it, or another name
fatal: 'upstream' does not appear to be a git repository
Cause: The remote is not configured
Add it with git remote add
Tips & Pitfalls
Best Practices
- ✓Name the original of a fork upstream.
- ✓Check git remote -v before your first push.
Common Mistakes
- ✗Expecting git remote add to download commits — run git fetch afterwards.
- ✗Pushing to upstream instead of origin in a fork.
FAQ
A:
git remote rename old new.
A:
git remote remove <name> — its remote-tracking branches go too.