Fetch, pull and push: keeping in step with the team

The interactive lesson needs JavaScript. The text below is the complete lesson.

After this lesson you can

• explain why your origin/main does not move when a colleague pushes, until you run git fetch understand
• choose between git fetch and git pull, and between --ff-only, --no-rebase and --rebase when you pull evaluate
• publish commits with git push, and resolve a rejected push by fetching, integrating and pushing again apply

Understand: Who knows what, and when?

You and Ada each have a clone of origin. Ada makes commit B and pushes. Main in origin moves to B. Your main and your origin/main still sit on A. Git sends you no notice. Nothing reaches your machine by itself.

git fetch asks origin what is new, downloads commit B and moves origin/main there. Your main does not move, and your files are unchanged. That is why fetch is safe at any time.

Then you must integrate. Here main is simply behind, so a merge can move main forward to B, a fast-forward. git pull does both steps in one command: first fetch, then integrate.

You make commit C. Only your main moves.

git push sends C and asks origin to move main. A normal push is accepted only as a fast-forward: the new commit must build on everything main in origin already has. C builds on B, so it works, and your origin/main follows.

But Ada has not fetched. She makes D on top of B and pushes. D does not build on C, so the push is not a fast-forward, and origin rejects it. Accepting it would throw C out of main. Nothing is broken.

The fix is always the same: fetch, integrate and push again. Ada runs git pull --no-rebase, which fetches C and makes the merge commit M. Now her push is a fast-forward. Forcing the push with --force would instead throw your C out of main.

Watch: Ada pushes, you are rejected, and you sort it out

Both you and Ada have a new commit that is not pushed. Ada is first. She pushes, and main in origin moves to her commit. Notice that your origin/main stays behind.

$ git push

Back in your repository. Ada has just pushed. What do you think git status says?

$ git status

We try to push anyway. Origin says no: rejected, fetch first. Origin has a commit you have never downloaded, and your push would throw it out of main. Nothing has changed. Read Git's hint.

$ git push

First we get the news. git fetch downloads Ada's commit and moves origin/main there. Your main stays put. Now the graph shows that the lines have split.

$ git fetch

Same question as before, new answer. Now Git knows about Ada's commit, and status says main and origin/main have diverged: one commit each.

$ git status

Now we integrate. git pull --no-rebase fetches and merges. The option says we want a merge commit. Without it, modern Git refuses to guess when the lines have split. Watch the new commit with two parents.

$ git pull --no-rebase

Now main contains both your commit and Ada's. The push is a fast-forward, and origin accepts it. Note that Ada's main does not move. It gets the commits only when she pulls.

$ git push

Tasks

1. As Ada: publish her new commit to origin.
2. Ask Git how main compares with its upstream.
3. Try to publish your commit, and read what origin replies.
4. Get what is new in origin, without changing your own main.
5. Bring Ada's commit into your main.
6. Publish main now that it contains Ada's work.

Practise: Transfer: this time Ada is rejected

This time you were first: your commit is already pushed, and Ada has an unpushed commit. Now Ada integrates with rebase instead of a merge commit. Git then replays her commit on top of yours, as a new copy, so main stays a straight line. That is safe because her commit exists only on her machine.

Tasks

1. As Ada: get her commit into origin without losing yours, and without a merge commit.
2. Back in your repository: update main so it equals main in origin. You have no commits of your own missing there.

Check yourself: Recall it

After git fetch, git status says main and origin/main have diverged, with 2 and 1 commits. Your two commits are also on the branch docs in origin, and Ada builds on them. How do you integrate?

• git pull --ff-only
• git pull --rebase
• git pull --no-rebase

What does git fetch change in your repository?

• Your main and the files in your working tree
• It downloads commits and moves remote-tracking branches such as origin/main
• Main inside origin

Your push is rejected as non-fast-forward. What do you do?

• git push --force, because my version is the right one
• Fetch, integrate the new commits and push again
• git push --force-with-lease, the safe kind of force

git pull with no options stops with “Need to specify how to reconcile divergent branches”. Why?

• Origin cannot be reached
• You have uncommitted files
• Both sides have new commits, and Git will not choose between merge and rebase for you

Recall from module 2: you are on main and run git merge feature. When is the result a fast-forward?

• When there are no conflicts
• When main has no commits that feature lacks, so main can simply move forward
• When feature has only one commit

Common misconceptions

• “origin/main updates itself when someone pushes.” Git talks to origin only when you ask it to. Until then origin/main shows what you last saw.
• “fetch changes my files.” fetch downloads commits and moves remote-tracking branches. Your main and your working tree stay untouched.
• “You fix a rejected push with --force.” That removes your colleague's commits from the shared main. The right fix is to fetch, integrate and push again.

$ git fetch
From /course/origin
   28e7a75..ef25355  main       -> origin/main

$ git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
...
fatal: Need to specify how to reconcile divergent branches.

$ git pull --ff-only
hint: Diverging branches can't be fast-forwarded, ...
fatal: Not possible to fast-forward, aborting.

 ! [rejected]        main -> main (fetch first)
hint: Updates were rejected because the remote contains work that you do not
hint: have locally.

 ! [rejected]        main -> main (non-fast-forward)
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart.