Using git fetch with --depth

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


In this guide, we'll explore the git fetch command with a focus on its --depth option. We will cover how --depth influences the behavior of git fetch, as well as other related options that modify the fetching process.

Fetch depth is typically used in shallow clones of repositories. For more information, see this guide on shallow cloning.

git fetch is a Git command used to download commits, files, and refs from a remote repository into your local repo, updating your remote-tracking branches. This command does not merge the changes into your current working branch unless explicitly done so with a subsequent merge command. It’s particularly useful before comparing the state of your local repository to that of the remote, as the command "fetches" all of the most recent changes.

The --depth option in git fetch is used to limit the number of commits Git downloads during the fetch process. This is known as a shallow fetch. It helps to reduce the amount of data transferred, speeding up the fetching process and decreasing the amount of storage used on your local machine.

The basic syntax for using --depth with git fetch is:

Terminal
git fetch <remote> --depth=<n>

Where <remote> is the remote repository, and <n> is the number of commits you want to include in the fetch.

  • Fetching with limited depth: To fetch only the latest commit, you can run:

    Terminal
    git fetch origin --depth=1

    This command fetches only the latest commit from the default branch of the remote repository.

  • Deepening a shallow fetch: If you have previously performed a shallow fetch and now need more history, you can "deepen" the fetch:

    Terminal
    git fetch --deepen=5

    This adds 5 more commits to your history from the remote tracking branch.

If you want to fetch all branches but only with a limited depth:

Terminal
git fetch --all --depth=1

This command fetches the latest commit from all branches but keeps the history shallow.

Sometimes, you might want to exclude tags when fetching to save time and space:

Terminal
git fetch --no-tags

This command will still fetch all of the commit metadata from the repository, while ignoring tags.

You can control the verbosity of the git fetch output:

  • Quiet fetch: This minimizes the output to the terminal.

    Terminal
    git fetch --quiet
  • Verbose fetch: This provides detailed information about what the fetch command is doing.

    Terminal
    git fetch --verbose

Using git fetch with the --depth option is particularly useful in continuous integration (CI) environments where you may only want to build and test the latest commits without waiting for the entire repository history to download.

It’s also beneficial when working on repositories with extensive commit histories where a full clone would be time-consuming and consume considerable bandwidth and storage.

In either case, it is best to use shallow fetching in addition to shallow cloning.

For further reading on the Git fetch command, see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2