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.

git fetch

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

A Common Scenario Example:

Here's a scenario to help you better understand this concept:

Assume there is a small development team consisting of two developers, Alice and Bob. They are working on a project hosted on a remote Git repository called origin. Alice clones the repository to her local machine and starts working on the main branch, while Bob is working on a separate branch called feature-branch.

1- Alice creates a new file called and makes some changes to it. She then commits and pushes her changes to the main branch on the origin repository:

$ git add
$ git commit -m "Add README file"
$ git push origin main

2- Meanwhile, Bob has made some changes to the feature-branch and pushed them to the origin repository:

$ git add some_file.txt
$ git commit -m "Add new feature"
$ git push origin feature-branch

3- Alice realizes that she needs to incorporate Bob's changes into her own work, so she fetches the changes from the origin repository:

$ git fetch origin

4- After fetching, Alice can see that there are new changes in the feature-branch:

$ git branch -r
  origin/HEAD -> origin/main

5- Alice can now merge Bob's changes into her main branch:

$ git merge origin/feature-branch

6- Alice resolves any merge conflicts, and then pushes her changes to the origin repository:

$ git push origin main

7- Bob can now fetch the changes made by Alice:

$ git fetch origin

8- Bob can now see that there are new changes in the main branch:

$ git branch -r
  origin/HEAD -> origin/main

9- Bob can merge the changes made by Alice into his feature-branch:

$ git merge origin/main

10- Bob resolves any merge conflicts, and then pushes his changes to the origin repository:

$ git push origin feature-branch

And so the cycle continues, with both Alice and Bob using git fetch to track changes made by each other and push their own changes to the origin repository. By using git fetch, they are able to keep their local repository up-to-date with the changes made by their teammates, which helps to avoid conflicts and ensure a smooth collaboration process.

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.

Practice Your Knowledge

What are the correct statements about the `git fetch` command as described in the W3Docs Git Tutorial?

Quiz Time: Test Your Skills!

Ready to challenge what you've learned? Dive into our interactive quizzes for a deeper understanding and a fun way to reinforce your knowledge.