How to Clone a Git Repository Along With Its Submodules

When you clone a Git repository with submodule(s) in it, by default you get the directories that contain submodule(s), but none of the files within them.

Clone with Submodules in One Command

If you pass --recurse-submodules option to the git clone command, it automatically initializes and updates all submodules in the repository, including nested ones if they exist.

git clone --recurse-submodules <repository_url>

For example:

git clone --recurse-submodules https://github.com/example/repo.git

Another Way to Initialize and Update Submodules

If you’ve already cloned a repository but forgot to use --recurse-submodules, you can run git submodule update --init to initialize and update the submodules. To make sure all submodules, including nested ones, are initialized, fetched, and checked out, use git submodule update --init --recursive.

git clone https://github.com/example/repo.git
cd <repository_directory>
git submodule update --init --recursive

Explanation

git submodule update: Ensures the submodules are synced with the specified commit in the parent repository.
--init: Initializes submodules if they haven’t been initialized yet.
--recursive: Applies the update to nested submodules, if any exist.

Note

In the context of submodules, the git submodule update command should not be confused with the general meaning of “update” as in “pulling the latest changes.” This command simply pins the submodule to the specific commit recorded in the parent repository.

Tip

To get the latest changes from the upstream repository of the submodule, you can use this command: git submodule update --remote --merge. See this post: Update Git Submodule to the Latest Commit for more details.

Additional Tips

1. Verify Submodules

To ensure that all submodules have been cloned and initialized correctly, you can run:

git submodule status

This command lists all submodules along with their current commit hashes. If any submodules are missing or not up-to-date, re-run the git submodule update --init --recursive command.

2. Cloning Without Submodules

If you’d like to clone a repository without its submodules, simply use the standard git clone command without initializing submodules.

By following these steps, you can effortlessly clone a Git repository along with its submodules. Submodules are powerful tools for managing dependencies, but they require careful handling to avoid errors.