Remotes and remote-tracking branches

Git · Essentials · 8 min

Collaboration in Git is exchanging commits between repositories, and remotes are how you name them.

A remote is a short name for another repository's URL. git clone creates one called origin automatically; in a repo you created with git init, you add it yourself with git remote add origin <url>. List them with git remote -v.

You can have several. In open-source work it's common to have origin (your fork) and upstream (the original project).

For each branch on a remote, Git keeps a remote-tracking branch such as origin/main. This is your local, read-only bookmark of where that branch was the last time you talked to the server. It only moves when you run git fetch, git pull or git push. It is not live: if a teammate pushes, your origin/main won't know until you fetch.

Your local main is a separate branch. Normally it has an upstream (tracking) relationship with origin/main, which is what makes git status say "ahead by 2, behind by 1" and lets bare git push/git pull know where to go. git branch -vv shows each branch's upstream and ahead/behind counts.

Other useful commands:

  • git remote show origin: details about branches on the remote.
  • git remote rename, git remote remove.
  • git remote set-url origin <new-url>: when a repository moves or you switch HTTPS to SSH.

Remotes are just configuration in .git/config; you can read it to see exactly what is set up.

Example

git remote add origin git@github.com:me/notes.git
git remote add upstream https://github.com/team/notes.git
git remote -v
# origin    git@github.com:me/notes.git (fetch)
# origin    git@github.com:me/notes.git (push)
# upstream  https://github.com/team/notes.git (fetch) ...

git fetch upstream           # update upstream/* bookmarks
git branch -vv
# * main 3f9a2c1 [origin/main: ahead 2, behind 1] Fix totals
git remote set-url origin https://github.com/me/notes.git

Remember

  • origin is just the default name clone gives the source remote
  • origin/main is a local bookmark, updated only by fetch/pull/push
  • Upstream tracking powers ahead/behind and bare git push/pull

Watch out for

  • Believing origin/main reflects the server right now — run git fetch first.

Check yourself

  1. A teammate pushed to main five minutes ago. You haven't fetched. What does your origin/main point to?

Sign in to answer, see the explanations, and get this lesson back as a quick review later.

Official docs: git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes