How to git clone recursively

Greg Foster
Greg Foster
Graphite software engineer

When working with Git, you may encounter repositories that include other repositories as "submodules". Cloning such a repository requires more than a simple git clone. In this guide, we'll explore how to effectively clone a Git repository along with its submodules recursively. This process involves several steps and commands, like git clone --recursive, git checkout submodule, and managing submodules after cloning. We'll also look into advanced topics such as checking out specific tags recursively and adding submodules after the repository has already been cloned.

Before diving into the cloning process, it's important to understand what submodules are. A submodule in Git is essentially a link to another repository at a particular snapshot. It allows you to keep a repository as a subdirectory of another repository, which helps in managing projects with multiple dependencies. This allows these sub-repositories to maintain their own histories and stay independent of the parent codebase.

To clone a repository and its submodules, you use the git clone --recursive command. This command initializes and updates each submodule in the repository, including nested submodules if any.

Terminal
git clone --recursive [URL to Git repository]

If you've already cloned a repository and forgot to use --recursive, you can fetch the submodules later using the following commands:

Terminal
git submodule init
git submodule update

This will fetch all of the current repository's submodules and make a copy of them in your local repository, allowing you to leverage them for building and running your code.

If your project depends on specific versions of submodules, you can checkout these versions recursively. This is useful in ensuring consistent builds or environments across different setups. Use the following command to checkout a specific tag across all submodules:

Terminal
git checkout [tag]
git submodule update --recursive --remote

This set of commands first checks out the main repository to the specified tag, then updates the submodules to match the commit specified in the main repository's submodule mapping.

Adding a new submodule to a repository that was already cloned is straightforward. Here’s how you can do it:

Terminal
git submodule add [URL to submodule repository] [path to submodule directory]
git submodule init
git submodule update

These commands add the submodule repository at the specified path and then initialize and update it.

If you've cloned a repository and need to manage its submodules (for example, add new ones or update existing), you can do so without re-cloning the entire repository. Here's how to add a submodule if you've already cloned the main repository:

Terminal
git submodule add [URL to the submodule repository] [destination directory]

This command adds the new submodule to your project and clones it to the specified directory.

For further reading on submodules and how to clone them recursively see the official Git documentation.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2