git pull: take other people's changes

git pull downloads new commits from the server and merges them straight into your current branch. One command does two steps: git fetch first, then git merge.

You pull before starting work and before every git push. The server refuses a branch that has fallen behind, and it is right to do so.

$ git pull
From github.com:username/my-project
   4f122d0..fb1befe  main       -> origin/main
Updating 4f122d0..fb1befe
Fast-forward
 notes.txt | 1 +
 1 file changed, 1 insertion(+)

The first two lines are the fetch: commits arrived and the origin/main pointer moved. The merge follows. The word Fast-forward means you had no commits of your own, so git simply moved the branch pointer forward without inventing anything.

If you were committing while other people were committing too, the histories have split, and git builds a merge commit:

$ git pull
From github.com:username/my-project
   fb1befe..9553949  main       -> origin/main
Merge made by the 'ort' strategy.
 readme.txt | 1 +
 1 file changed, 1 insertion(+)

A conflict during pull

When you and a colleague edited the same spot in the same file, the automation gives up:

$ git pull
From github.com:username/my-project
   9553949..b0a71c4  main       -> origin/main
Auto-merging conf.txt
CONFLICT (content): Merge conflict in conf.txt
Automatic merge failed; fix conflicts and then commit the result.

This is routine, not a disaster, and nothing is lost yet. Open the file, pick the version you want, remove the <<<<<<<, ======= and >>>>>>> markers, then git add and git commit. git merge --abort puts everything back the way it was before the pull. Step by step in merge conflicts.

pull --rebase

The other way to join a split is to move your commits on top of everyone else's, with no merge commit:

$ git pull --rebase
From github.com:username/my-project
   58d82b3..f2b0989  main       -> origin/main
Successfully rebased and updated refs/heads/main.

The history comes out as a straight line: other people's commits first, yours after. The price is that your commits get new hashes. For a branch you have not pushed yet that is safe; the rules and limits are in git rebase.

Your first pull ever may print You have divergent branches and need to specify how to reconcile them instead of a result. Git is asking which of the two ways you want. You answer once:

$ git config --global pull.rebase false   # join through a merge
$ git config --global pull.rebase true    # move your commits on top

Common mistakes

A pull with uncommitted edits stops at error: Your local changes to the following files would be overwritten by merge. Commit the work or put it aside with git stash, then try again.

Pull also merges into whichever branch you are standing on right now. If your task lives in its own branch but the main one needs updating, run git switch main first.

Where this is in the book

Chapter 6. GitHub: the cloud and working together.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.