git fetch: see what is new on the server

git fetch downloads fresh commits from the server without touching your branch or the files on disk. It is reconnaissance: find out what is going on, then decide whether to merge now or finish your own piece first.

$ git fetch
From github.com:username/my-project
   773e133..4f122d0  main       -> origin/main

The line reads like this: the branch main on the server moved from commit 773e133 to 4f122d0, and your local origin/main pointer now looks there too. Your working directory is unchanged, and git status shows what it showed a minute ago, just with a new summary:

$ git status
On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

What origin/main is

origin/main looks like a branch, but it is only half yours. It is a local pointer to where the branch main stood on the server at the moment of your last exchange. It lives on your disk, reads instantly with no network, and only git fetch and git pull ever move it.

Since it is an ordinary point in the history, all the usual commands work on it:

$ git log origin/main --oneline
4f122d0 rewrote the install section
773e133 first version

$ git log main..origin/main --oneline    # only what you do not have
4f122d0 rewrote the install section

$ git diff main origin/main --stat       # which files are coming
 readme.txt | 1 +
 1 file changed, 1 insertion(+)

The difference from pull

git pull is git fetch plus git merge in one command. Fetch does only the first half, so it cannot spoil your working directory: no conflict, no risk to uncommitted edits. Once the picture is clear, you merge as a second step with git merge origin/main or simply with git pull.

The --prune flag also removes pointers for branches that no longer exist on the server:

$ git fetch --prune
From github.com:username/my-project
 - [deleted]         (none)     -> origin/gone-branch

Common mistakes

The first one is expecting your files to change after a fetch. They do not. The command updates pointers like origin/main, while the working directory stays where your last commit left it.

The second is reading git log origin/main without a fresh fetch. The pointer never moves on its own, so with no exchange you are looking at yesterday's picture and drawing conclusions from it.

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.