Module 7 Lesson 3: Cloning repositories with submodules

If you git clone a project that contains submodules using the standard command, you will notice something strange: the folders where the submodules should be are empty.

This is because Git doesn't automatically download submodule content by default (to save time and bandwidth). In this lesson, we learn how to correctly "populate" those empty folders.

---

1. The Pro Way: Recursive Clone

If you know a project has submodules, you can tell Git to download everything in one go:

git clone --recursive <url>

This command clones the parent project and then automatically initializes and updates every submodule it finds.

---

2. The Manual Way: If you've already cloned

If you forgot the --recursive flag and already have the project on your disk with empty folders, you need to run two commands:

Step 1: Initialize

This command looks at your .gitmodules file and copies the configuration into your local .git/config file.

git submodule init

Step 2: Update (Download)

This command actually connects to the remote servers and downloads the code into the folders.

git submodule update

Shortcut: You can combine these two into: git submodule update --init.

---

3. Nested Submodules

Sometimes a repository has a submodule, and that submodule has its own submodules. To handle these "Russian Doll" repositories:

git submodule update --init --recursive

graph TD
    Project["Parent Project (Cloned)"]
    EmptyDir["Empty Folder (libs/ui)"]
    
    Project -- "git submodule update --init" --> Download["Download UI Lib"]
    Download --> PopulatedDir["Filled Folder (libs/ui)"]

---

Lesson Exercise

Goal: Fix an "Empty" repo.

1. Find a repository on GitHub that uses submodules (e.g., search for projects with a .gitmodules file).
2. Clone it normally: git clone <url>.
3. Go into the submodule folder. Is it empty? (It should be).
4. Run git submodule update --init.
5. Is the code there now? (It should be!).

Observation: You'll realize that as a consumer of a project, the --recursive flag is your best friend. It ensures you have a working environment from second one.

---

Summary

In this lesson, we established:

• Standard git clone does not download submodule content.
• --recursive is the easiest way to clone and populate submodules simultaneously.
• git submodule update --init is the manual way to download content after a clone.

Next Lesson: External libraries don't stay still. We’ll learn Lesson 4: Updating and synchronizing submodules.