How do I “git clone” a repo, including its submodules?

To clone a Git repository including all submodules, use the --recurse-submodules flag. This ensures the main repository and its submodules are initialized and updated in one step.

1. Clone with Submodules (Recommended)

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

• --recurse-submodules: Clones the repository and initializes/updates all nested submodules.

2. Initialize Submodules After Cloning

If you already cloned the repository without submodules, run:

git submodule update --init --recursive

• --init: Initializes submodules (creates .git/modules entries).
• --recursive: Handles nested submodules (submodules within submodules).

3. Update Existing Submodules

To fetch the latest changes for submodules:

git pull
git submodule update --recursive --remote

• --remote: Pulls the latest commits for submodules from their upstream repositories.

4. Speed Up Cloning (Parallel Fetch)

For large repositories, use --jobs to parallelize submodule fetching:

git clone --recurse-submodules --jobs 4 https://github.com/username/repo.git

Example Workflow

1. Clone with submodules:

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

2. Check submodule status:

   git submodule status

3. Update submodules later:

   git submodule update --recursive --remote

Key Notes

• Submodule Configuration: Defined in .gitmodules (paths and URLs).
• Nested Submodules: Always use --recursive to initialize all levels.
• Security: Submodules may point to external repositories—verify their trustworthiness.

Troubleshooting

• Empty Submodule Directories: Run git submodule update --init --recursive.
• Permission Issues: Ensure you have access to all submodule repositories.
• Detached HEAD: Submodules are checked out at specific commits (not branches).