Quick Links

Key Takeaways

The git fetch command is like a git pull command that updates your local repository with information and commits from the remote repository, without overwriting your working files.

The Git fetch command lets you look before you leap. You can discover what changes have been made to a remote repository, but without overwriting your local files with the remote files.

What Is git fetch, and What Does It Do?

The fetch command in Git downloads commits, files, and other information from a remote repository to your local repository, safely. Use fetch when you want to see what changes other developers have made, without being forced to accept the changes. Your local files remain untouched. Why is that important?

You have to keep your wits about you when you're working as part of a development team. The remote or central repository will contain changes and new branches that other developers have created and pushed to the remote repository.

It's entirely possible that someone has updated the remote copy of files that you've modified locally on your computer. If you casually perform a git pull to update your local repository, you're likely find to yourself handling merges for changes you might not even want.

Once you've downloaded the information, you can examine it and see what the changes are. This lets you make an informed choice about what you want to merge right now, if anything, and what you want to defer until later.

Git fetch vs. pull

The git fetch command behaves like the git pull command but without the step that overwrites your local files. Your local repository is updated and synchronized, but the changes are not written to your local repository's working state, so your files remain untouched.

Or, to put it another way, the git pull command is like a git fetch followed immediately by a git merge .

Sync Your Local and Remote Repositories With git fetch

To fetch all the updated metadata and commits from a remote repository to your local repository, use the git fetch command with the name or URL of the remote repository. By default, the first remote repository is called "origin."

git fetch origin

You can omit the word "origin" if you're working with a single remote repository.

git fetch

Using the git fetch command on the default remote repository

That retrieves any updates from the "origin" repository, but it doesn't merge the changes into the working files. We can see there is a new branch, called "new-branch", that has been retrieved for us.

Once you've used the fetch command, you can see see the full list of branches on the remote, by using -r (remote) option with the branch command.

git branch -r

Looking at the branches that exist on the default remote

This lists all the branches that the remote knows about, which after the fetch , are also in your local repository.

See All Fetched Tags

Similarly, you can use the tag option (note, it's "tag" without an "s") to see the list of tags.

git tag

Using the git tag command to list the tags in the local repository

Doing a Dry Run First

Although a git fetch doesn't merge the changes into your working files, it does still update your local repository. If you want to see what change the fetch command will perform, without actually making them, use the --dry-run option.

git fetch --dry-run

Using the --dry-run option so see the changes the fetch command would retrieve

How to Fetch a Single Branch

Fetching information about a single branch is easy. Add the name of the branch to the command line to tell fetch you only need to know about that one branch.

Here, we're telling fetch to retrieve the branch "mary-feature" from the remote repository "origin."

git fetch origin mary-feature

Using git fetch to retrieve a single remote branch

Now that the details and contents of the remote branch are in your local repository, you can use the git checkout command to create a new branch and checkout the remote branch. This won't over-write any existing files if it's the first time you've used this branch.

git checkout -b mary-feature origin/mary-feature

Safely checking out a retrieved remote branch to a new local branch

Fetch All Branches

If you're using multiple remotes, you can save time by pulling all changes from all branches back to your local repository by using the --all option.

git fetch --all

Comparing Local and Remote Branches

To see how the files in a remote branch differ from your local copies, use git fetch , then use the git log command.

Note that the local and remote branches have two periods ".." separating them. The --oneline option shows the commit identifier and the commit message.

git fetch

git log --oneline mary-feature..origin/mary-feature

Using git to fetch the remote changes and git log to show the changes

The one-line display is useful if a branch contains a great many changes. To see a little more information, omit the --oneline option.

git log mary-feature..origin/mary-feature

Using the git fetch command on the default remote repository

This shows us the time and date of each commit, together with the commit message and the contact details of the change author.

Synchronizing a Local Branch with a Remote Branch

If you've decided you want to go ahead and merge the changes from the remote branch to your local working files, you can use these commands.

We'll checkout the branch to make sure we're working it is our current, working branch..

git checkout mary-feature

Using the git fetch command on the default remote repository

The branch is checked out for us, and we're told that it is behind the remote version. We can use git pull to update it, then git status to check our status.

git pull

git status

Using the git fetch command on the default remote repository

If we've made some changes to our local files, Git informs us when we checkout the branch that we'll need to perform a git pull to start a merge.

git checkout mary-feature

Using the git fetch command on the default remote repository

A simple git pull starts the process of retrieving the files and merging, or we can dive right in and use git merge itself. We'll start by making sure we're working with the correct branch

git checkout mary-feature

Using the git fetch command on the default remote repository

We'll tell git to merge our current branch with the branch in the remote repository, there are six different commits that need to be resolved.

Using the git fetch command on the default remote repository

We need to tell Git which remote branch we want to merge.

git merge origin/mary-feature

Using the git fetch command on the default remote repository

An editor opens to allow us to provide a commit message. We can accept the suggested message, or add our own. The editor is your default editor unless Git has been configured to use a different editor.

Using the git fetch command on the default remote repository

Save your changes when you are ready to proceed. The merge carries on automatically when the editor is closed.

Our merge was successful because there were no conflicts.

Using the git fetch command on the default remote repository

Conflicts arise when the same lines of code are changed by two or more developers. If that is the case, Git marks up the conflicts in the affected file. You'll need to review them in turn and choose which change to keep.

The Half-Trained Puppy

Just like a puppy in training, fetch will retrieve what you ask for, but it won't drop it. If you actually want what the puppy has shown you, you'll need to pull.

Related: Git rebase: Everything You Need to Know