Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 78 ยท Remotes and Collaboration

push, pull and Tracking Branches

Learn git push and git pull in depth: upstream tracking, rejected pushes, divergent branches, merge versus rebase pulls, --force-with-lease, tags and push.default.

Remotes showed you how to connect repositories and download from them. This lesson is about the two commands you will run dozens of times a day: git push sends your commits to a remote, and git pull brings other people's commits into your branch. Both are simple when history is a straight line and both produce famous error messages when it is not.

The concept that ties everything together is the tracking relationship (also called the upstream): a local branch that knows which remote branch it belongs to. Once that link exists, plain git push, git pull and git status all know what to compare and where to send things. We will set it up, break it on purpose with a rejected push, fix it three different ways, and finish with the dangerous --force family and what to do about it.

Every example uses a bare repository on disk (server.git) as the remote, because our runner has no network. A local path behaves like https://github.com/you/project.git for everything in this lesson. The messages mention server.git instead of a URL, and a few lines are filtered with sed to hide the path.

What push does

git push <remote> <branch> uploads the objects the remote does not have yet and then asks the remote to move its branch to your commit. The remote only agrees if that move is a fast-forward: the new commit must have the old remote tip as an ancestor. In other words, a push can add to a branch's history, never silently erase it.

TEXT
   remote main:   A---B
   your main:     A---B---C---D        push: fast-forward, accepted

   remote main:   A---B---X
   your main:     A---B---C---D        push: NOT a fast-forward, rejected

After a successful push Git also moves your remote-tracking branch (origin/main), so git status immediately knows you are in sync.

Upstream (tracking) branches

A local branch can have an upstream: the remote branch it normally pushes to and pulls from. It is stored as two settings in .git/config, branch.<name>.remote and branch.<name>.merge. git clone sets it up for the default branch. For every other branch you create it with -u (short for --set-upstream) the first time you push.

Without an upstream, a bare git push does not know where to go and refuses. With one, git status -sb tells you at a glance how you relate to the server.

Bash Setting an upstream with push -u

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first plain git push failed with fatal: The current branch main has no upstream branch. and Git printed the exact command to fix it. git push -u origin main pushed and wrote the two config lines (branch.main.remote origin, branch.main.merge refs/heads/main); git branch -vv now shows [origin/main] next to main. The status line ## main...origin/main means "in sync"; after one new commit it read [ahead 1], and after pushing it was back to in sync.

The same refusal happened for the new branch topic. Rather than typing -u every time you can run git config push.autoSetupRemote true (the first push of a new branch then sets the upstream automatically, as the second git push above shows). Finally git push --delete origin topic removed the branch on the server; only refs/heads/main was left.

git push -u origin HEAD pushes the current branch under its own name, whatever it is called. It is a good habit for the first push of a new branch, because you cannot mistype the branch name.

Rejected pushes: the non-fast-forward error

Sooner or later this happens: a teammate pushed while you were working. Your push is then not a fast-forward, and the server says no. Nothing was lost or damaged; Git simply protected the other person's commits.

Bash A rejected push and how it looks (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first error line, ! [rejected] main -> main (fetch first), says the server has commits you have not fetched. The hint suggests git pull, but with no configuration modern Git refuses even that when your branch and the server's have diverged (each side has commits the other lacks): fatal: Need to specify how to reconcile divergent branches. The fetch part of the pull did succeed, so origin/main is now current; only the integration step was refused. You must choose how to integrate, and there are three options.

Divergence: merge, rebase or fast-forward only

First, look at the situation. After a fetch, git status -sb shows [ahead 1, behind 1], and git rev-list --left-right --count main...origin/main prints the two numbers (commits only on your side, commits only on theirs). Then pick a strategy:

Strategy Command Result
Merge git pull --no-rebase (pull.rebase false) a merge commit joins the two lines
Rebase git pull --rebase (pull.rebase true) your commits are replayed on top of the server's, linear history
Fast-forward only git pull --ff-only (pull.ff only) succeeds only if no merge is needed, otherwise stops and lets you decide
Bash Diverged: ahead 1, behind 1, then merge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

rev-list --left-right --count printed 1 1: one commit on each side. With pull.ff only Git fetched and then stopped with fatal: Not possible to fast-forward, aborting., changing nothing. The merge pull created a merge commit ("Merge branch 'main' of server") with two parents; in the graph you can see my commit "I add c" on one line and the teammate's b and d on the other. Merging is safe and records the truth: the work really happened in parallel.

The rebase alternative gives a straight line:

Bash pull --rebase gives linear history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git pull --rebase fetched, then replayed "I add c" on top of the teammate's commit (the output says Successfully rebased and updated refs/heads/main.). The log is a straight line, and my commit has a new hash, because a commit's identity includes its parent. The status line afterwards still says ahead 1, so a normal push is accepted.

Which should you choose? Most teams standardise on one; set it once and forget it: git config --global pull.rebase true (linear history) or pull.rebase false (merge commits). The Rebasing lesson explains the trade-offs and the golden rule: only rebase commits that you have not shared. A pull-rebase of your own unpushed work is always fine.

git pull --ff-only is the cautious daily driver: it updates when the update is trivial, and otherwise stops so you can look with git log origin/main and then decide to merge or rebase yourself. Combine it with git config --global pull.ff only.

What pull really does

git pull is git fetch followed by git merge @{upstream} (or a rebase). The @{upstream} part, also written @{u}, is the revision name for "the upstream of the current branch" (see Revision Syntax). That is why a branch without an upstream cannot be pulled:

CONSOLE
$ git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.

(That is a read-only sample of the message; the fix is git branch --set-upstream-to=origin/main or git pull origin main.) If a pull stops in the middle of a rebase or merge because of conflicts, you resolve them as described in Resolving Merge Conflicts and continue.

One more helpful option: git pull --autostash (or rebase.autoStash true) stashes your uncommitted changes, pulls and reapplies them, so a dirty working tree does not block a rebase. See Stashing Work in Progress.

Force pushes and --force-with-lease

Sometimes you really do want to rewrite what the server has, typically after an amend or rebase of a branch that only you use. Then a normal push is rejected on purpose and you need --force. There are two flavours and the difference matters enormously:

  • git push --force says: "make the remote branch exactly this, whatever is there." It will happily delete a teammate's commits.
  • git push --force-with-lease says: "overwrite the remote branch, but only if it still points where my remote-tracking branch says it does." If someone pushed in the meantime, it refuses.
Bash force-with-lease protects a teammate's push

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first --force-with-lease was rejected with (stale info): my origin/main did not match the server, so Git knew somebody else had pushed. But look at the second attempt. I ran git fetch, which refreshed origin/main, and now the lease check passed (forced update) and the teammate's commit "Teammate builds on b" vanished from the server: the final log has only my two commits. A lease is only as good as your last look. A fetch you did not read, a background IDE auto-fetch or a git pull run before the force push all reset the lease. The safe habit: after fetching, check git log origin/main.. or git range-diff, and only force when you know what you are replacing. You can also pin the expected value: git push --force-with-lease=main:<hash>.

Never force-push to a shared branch such as main or develop. Turn on branch protection on your hosting platform (see Signing, Credentials and Security) so that the server rejects it for you. If you do break a branch, the old tip usually still exists in someone's reflog; see The Reflog.

Tags, --all and other push forms

Tags are not pushed automatically. A plain git push sends branches only. You send tags explicitly, which is deliberate: tags are releases, and you should decide when one becomes public.

Bash Pushing tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The plain push sent the new commit only (main -> main) and the server had no tags at all. Pushing v1.0 by name worked. --follow-tags pushed the commits and the annotated tags reachable from them (v1.1 and v1.2), but not the lightweight v1.2-rc; the ^{} lines in ls-remote are the commits those annotated tags point at. --tags pushes every tag, including lightweight ones, which the dry run shows (v1.0 is listed because we had deleted it remotely). Deleting a tag on the server is git push origin --delete <tag>; deleting it locally is git tag -d. More about releases in Tags and Releases.

Other forms you will meet:

  • git push origin main:release pushes local main to the remote branch release (the general form is <local>:<remote>, a refspec; see Transfer Protocols).
  • git push origin :old-branch is the old spelling of --delete.
  • git push --all origin pushes every local branch; git push --mirror makes the remote an exact copy (including deletions), which is for backups only.
  • git push --dry-run shows what would happen without doing it.

push.default: what a bare git push does

push.default decides which branch a plain git push sends. Since Git 2.0 the default is simple: push the current branch to the same-named branch of its upstream, and refuse when the names differ. Other values: current (push to a same-named branch, even without an upstream), upstream, matching (all branches with the same name on both sides, the dangerous pre-2.0 behaviour) and nothing. Leave it at simple unless you have a strong reason, optionally with push.autoSetupRemote true for the convenience shown earlier.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does git push -u origin feature do beyond pushing?

    -u (--set-upstream) writes branch.feature.remote and branch.feature.merge, so later plain push, pull and status know which remote branch to use.
  2. 2. Your push is rejected with 'fetch first'. What does it mean?

    Someone else moved the remote branch. Fetch, integrate with merge or rebase, then push again. Nothing was lost.
  3. 3. Which pull strategy keeps a strictly linear history?

    --rebase replays your local commits on top of the fetched ones, producing a line (and new hashes for your commits). --no-rebase creates a merge commit.
  4. 4. Why can git push --force-with-lease still overwrite a teammate's work?

    The lease means 'only if the remote is still where origin/<branch> says'. If you fetched the teammate's commits without noticing and then force-pushed an older line, they are replaced. Review what you fetched before forcing.
  5. 5. How do you send an annotated tag along with a normal push?

    --follow-tags pushes commits plus annotated tags that point at them. Plain push sends no tags; --tags sends all tags including lightweight ones.

Summary

  • git push uploads commits and moves a remote branch, but only by fast-forward; otherwise the push is rejected and nothing is lost.
  • An upstream (branch.<name>.remote and .merge) links a local branch to a remote branch; set it with git push -u, or automatically with push.autoSetupRemote.
  • git pull is fetch plus merge or rebase of @{upstream}. Diverged branches require a choice: pull.rebase false (merge), true (rebase) or pull.ff only.
  • git status -sb and git rev-list --left-right --count main...origin/main show ahead and behind counts relative to your last fetch.
  • Use --force-with-lease, never plain --force, and remember that fetching resets the lease; never force-push shared branches.
  • Tags are not pushed by default: use git push origin <tag>, --follow-tags (annotated) or --tags (all).
  • push.default is simple: the current branch to its same-named upstream.

Next: Collaboration Workflows