What is a remote?

A copy of the repository somewhere else, the branch that tracks it, and the three commands that move commits between the two.

A remote is another copy of the repository, usually on a server, with a name in yours. The name is origin by default, which is what a clone calls the place it came from. Your repository and the remote are both complete: neither is the master copy, and nothing moves between them until you ask.

Three commands do the asking. Fetch brings down what the remote has and changes nothing you are working on. Pull is a fetch followed by combining what arrived with your branch, by merge or by rebase. Push sends your commits up and moves the remote’s branch to match.

What you see of the remote in between is a remote-tracking branch, a name like origin/main: your record of where the remote’s main was the last time you looked. It moves when you fetch and when you push, never when you commit.

  1. main and origin/main both at C. As far as your repository knows, you and the remote agree.

  2. Fetch. Someone had pushed D: it comes down, and origin/main moves to it. main has not moved, and nothing on disk has changed.

  3. Pull: the fetch, then main catches up. main had no commits of its own since C, so this one is a fast-forward to D.

  4. A commit of yours. main moves to E; origin/main stays at D. You are one commit ahead of the remote.

  5. Push. E goes up, the remote's main moves to it, and origin/main records that.

Ahead, behind, and both

Comparing main with origin/main gives the two numbers a Git client shows beside a branch: ahead is your commits the remote does not have, behind is its commits you do not have. Both at once means the two have diverged, and a pull has something to combine, as a merge commit or as a rebase of your commits on top of theirs. A push is refused while you are behind, because it would throw the remote’s commits away; pull first.

Which remote branch a local branch is measured against is its upstream. It is usually set the first time the branch is pushed.

On the command line

git remote -v      # the remotes and their URLs
git fetch          # bring down what the remote has
git pull           # fetch, then merge or rebase into the current branch
git push           # send your commits; -u sets the upstream the first time

Git’s own reference: git-fetch, git-pull, git-push and git-remote. The Pro Git book covers the same ground.

In Innesta

The toolbar’s three buttons, and the one command that picks between them, are on sync. Pulling safely is the fetch that comes first and the three ways your commits and theirs are combined; pushing shows what is about to go. Remotes is where they are added, and the upstream branch is the measure the ahead and behind badges use. A remote’s starting point is a clone.

The Playground has no remote, so this is one to try on a clone of something you own.