Remotes: clone, fetch, pull and push

Intermediate

Introduction

So far everything has happened in one repository. Real work involves several copies: yours, your teammates', and a shared one on a server such as GitHub. Git connects them with remotes. Because every copy has the full history, synchronizing is just exchanging the commits one side is missing, and the same ancestry rules from earlier lessons decide what is safe.

How it works

git clone URL copies a repository, sets up a remote called origin pointing at the URL, and creates a local main that tracks origin/main. URLs come in two common forms: HTTPS (https://github.com/owner/repo.git) and SSH (git@github.com:owner/repo.git).

Remote-tracking branches such as origin/main are your local record of where the remote's branches were the last time you talked to it. You never commit to them; git fetch updates them by downloading new commits.

Comparing your branch with its upstream gives:

  • ahead by N: N commits on your branch that the remote does not have (push them);
  • behind by M: M commits on the remote you do not have (pull them; a fast-forward is possible);
  • diverged: both at once; pulling will need a merge or a rebase.

git pull is git fetch followed by merging the upstream into your branch (or rebasing onto it with git pull --rebase).

git push sends your commits and asks the remote to move its branch. The remote accepts only a fast-forward: its current tip must be an ancestor of what you push. If someone else pushed first, your push is rejected; you must fetch and integrate their work first. git push --force overrides this and can destroy others' commits; git push --force-with-lease is the safer form: it only forces if the remote is still where you last saw it.

git clone https://github.com/owner/repo.git
git remote -v                    # list remotes
git fetch                        # update origin/*
git status                       # ahead / behind
git pull                         # fetch + merge
git push -u origin feature       # push and set the upstream
git push --force-with-lease      # force only if nobody else pushed

Example

parents = {"a": [], "b": ["a"], "c": ["b"], "x": ["b"], "y": ["x"]}


def reachable(tip):
    seen, stack = set(), [tip]
    while stack:
        oid = stack.pop()
        if oid not in seen:
            seen.add(oid)
            stack.extend(parents[oid])
    return seen


def status(local, remote):
    ahead = len(reachable(local) - reachable(remote))
    behind = len(reachable(remote) - reachable(local))
    return ahead, behind


remote_main = "b"
local_main = "c"
print("before fetch: ahead/behind =", status(local_main, remote_main))
remote_main = "y"
print("a teammate pushed x and y; after git fetch: ahead/behind =", status(local_main, remote_main))
ahead, behind = status(local_main, remote_main)
print("git push would be rejected:" if behind else "git push would succeed:", "remote has commits we do not have" if behind else "")
parents["m"] = [local_main, remote_main]
local_main = "m"
print("after git pull (merge): ahead/behind =", status(local_main, remote_main))
remote_main = local_main
print("after git push: ahead/behind =", status(local_main, remote_main))
Open in compiler

Line by line

  1. status counts commits reachable from one tip but not the other, in each direction.
  2. With one local commit c on top of the remote's b, the branch is ahead by 1.
  3. After a teammate pushes x and y and we fetch, we are ahead by 1 and behind by 2: diverged, so a push would be rejected.
  4. Pulling creates a merge commit m joining both lines; now we are only ahead.
  5. Pushing moves the remote branch to m, and the two are equal again.

Expected result

before fetch: ahead/behind = (1, 0)
a teammate pushed x and y; after git fetch: ahead/behind = (1, 2)
git push would be rejected: remote has commits we do not have
after git pull (merge): ahead/behind = (2, 0)
after git push: ahead/behind = (0, 0)

In the real world

Teams usually have one shared remote on GitHub or GitLab, where protected branches reject direct and forced pushes, and changes arrive through pull requests. Open-source contributors often have two remotes: origin (their fork) and upstream (the original project). CI servers fetch the exact commit they need and never push.

Common mistakes

  • Using git pull with uncommitted work, which can make a messy merge harder to undo.
  • Force-pushing a shared branch and erasing teammates' commits.
  • Thinking origin/main updates by itself: it changes only when you fetch.
  • Forgetting -u on the first push, so later git pull does not know what to track.

Best practices

  • Fetch often; it never changes your work.
  • Pull before starting new work and before pushing.
  • If you must force-push your own branch, use --force-with-lease.

Summary

Remotes connect copies of a repository; remote-tracking branches record where the remote's branches were at the last fetch. Ahead and behind counts compare your branch with its upstream. Pull is fetch plus merge or rebase, and a push is accepted only as a fast-forward unless forced, preferably with --force-with-lease.

Quick check

1. What does git fetch change?
2. Your branch is behind origin/main by 3 commits and not ahead. What does git pull do?
3. Why is a push rejected?
4. What does --force-with-lease add over --force?

Key takeaways

  • git fetch is always safe; git pull = fetch + merge (or rebase).
  • Ahead counts your commits the remote lacks; behind counts the remote's commits you lack.
  • A push is accepted only if it fast-forwards the remote branch, unless you force it.

Practice problems for this lesson

My notes

Write down what you want to remember from this lesson. Notes are saved on this device as you type, and appear on your dashboard.