Git fetch

  1. Definition
  2. How it works with remote branches
  3. Common Options
  4. How to git fetch the remote branch
  5. Synchronizing origin with git fetch
  6. Git fetch vs git pull


The git fetch command is used to download commits, files and references from a remote repository into the local repository. It is used to see what other members of the team have been working on.

How it works with remote branches

Git stores the local and remote commits and separates through the use of branch references. The references for the local branches are stored in the /.git/refs/heads/. So as to see the list of the local branch references, run the git branch command.

git branch

Exploring the contents of the /.git/refs/heads/ directory will have the following output:

ls ./.git/refs/heads/

Remote branch references are stored in the ./.git/refs/remotes/ directory. To see the remote branches, use the -r flag with the git branch. Here is the output after fetching a remote repository:

git branch -r
# origin/master
# origin/crossword
# origin/solver
# remote-repo/master
# remote-repo/other-feature

The output displays with prefix origin/ which shows the remote branches. You can examine the remote branches with the git checkout and git log commands. After approving the changes of the remote branch, you can merge it into the local branch with the git merge command. Use the git pull command instead to shorten the process.

Common Options

--all​ Fetches all the remote branches.
--dry-run Shows the demo run of the command without making changes.
-k or --keep Keeps downloaded pack.
-p or --prune Removes the remote-tracking references not existed on the remote before fetching.
--depth=<depth> Limits the number of commits to fetch from the tip of each remote branch history.

How to git fetch the remote branch

Here, we will show the steps of fetching a remote branch and update the local working state to the remote content. In the following example, we have a central repository origin from which the local repository has been cloned with the git clone command. There is another remote repository named test_repo containing feature_branch that has to be configured and fetched.

The first step is configuring the remote repository with git remote:

git remote test_repo git@hostname:test/test_repo.git

Using the URL of the coworker’s repository, we have created a reference to it. For downloading the content git fetch the test feature_branch:

git fetch test feature_branch
fetching test/feature_branch

This will integrate the content of the test/feature_branch to the local repository. Now, use the git checkout command to checkout the downloaded remote branch:

git checkout test/feature_branch
Note: checking out test/feature_branch'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can drop all the commits you make in this
state without influencing branches by executing another checkout.

If you want to generate a new branch for maintaining commits you create, you may
do so (now or later) if you use -b with the checkout command again. Example:

git checkout -b <new-branch-name>

The output shows that we are in the detached HEAD state which means that the HEAD reference points to a reference not being in sequence with the local history.

With the git checkout command a new local branch from the test/feature_branch reference may be created:

git checkout -b local_feature_branch

The new local branch is created updating HEAD to point at the latest remote content.

Synchronizing origin with git fetch

The following example displays how to synchronize the local repository with the central repository's master branch:

git fetch origin

The output will show the branches that have been downloaded:

b341bc3..32a45b1 master -> origin/master
b341bc3..7a52a22 develop -> origin/develop
* [new branch] some-feature -> origin/some-feature

Invoke git log using origin/master as a filter to show the commits added to the upstream master:

git log --oneline master..origin/master

Check the changes and merge them into the local master branch:

git checkout master
git log origin/master

Run git merge origin/master to synchronize with the upstream developments:

git merge origin/master

Git fetch vs git pull

Both git fetch and git pull are used for downloading the content from the remote repository. The git fetch command does not force to merge the changes into the repository, it just shows the progression of the central history. The fetched content does not have any effect on the local work, and it should be checked out using the git checkout command making it safe to review commits before merging them into the local repository. The git pull command not only downloads the new content but also directly integrates it into the current working copy. This can cause merging conflicts. Also, it is recommended to run git pull only when the working copy is clean.

Do you find this helpful?

Related articles