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

Click any option to expand

Beginner (1)

Show the URL of each remote, for fetch and push.

RecommendedSee exactly which URL you fetch from and push to

Example

git remote -v

Choosing the Right Option

origin vs upstream

The two usual remotes of a fork

CommandPoints toYou push?
originYour copy (the fork)Yes
upstreamThe original projectNo — you fetch from it

Examples

List remotes

git remote -v

Names with their URLs.


Add the original of a fork

git remote add upstream git@github.com:acme/shop.git

A second remote.


Change a URL

git remote set-url origin git@github.com:you/shop.git

E.g. switch from HTTPS to SSH.


Details

git remote show origin

Branches and tracking information.

Workflow Examples

1
git remote add upstream git@github.com:acme/shop.git

Once

2
git fetch upstream

Download its commits

3
git merge upstream/main

Bring them into your main

4
git push

Update 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.