Adding and Cloning Submodules

Git submodules let you embed one Git repository inside another. This is useful for managing external dependencies like libraries or shared components.

In this lesson, we'll learn how to add a new submodule to your project and how to properly clone a repository that contains submodules.

To add a submodule, you use the git submodule add command. This command takes the URL of the external repository and optionally a local path where you want to place it.

• Repository URL: The URL (HTTPS or SSH) of the submodule's Git repository.
• Path: The directory within your main project where the submodule will reside. If omitted, Git uses the repository name.

Let's say you have a my-project repository and want to include a shared library from https://github.com/example/shared-lib.git.

First, navigate to your main project's directory.

After running git submodule add, Git does a few things:

• It clones the submodule repository into the specified path (e.g., lib/shared-lib).
• It adds an entry to a special file called .gitmodules in your main repository's root.
• It stages the new submodule directory and the .gitmodules file for commit.

The .gitmodules file is a configuration file that stores the mapping between the submodule's local path and its remote URL. It's crucial for others to clone your project correctly.

Here's what it might look like for our example:

Adding a submodule is a change to your main repository, so you need to commit it. The commit will record the specific commit hash of the submodule's repository that your main project is currently using.

When you clone a repository that contains submodules, Git clones the parent repository but doesn't automatically download the submodule content.

The submodule directories will appear empty or contain only a .git file pointing to the submodule's repository.

The most straightforward way to clone a repository and all its submodules is to use the --recurse-submodules flag with git clone.

This command clones the main repository and then automatically initializes and updates all submodules to their correct versions.

If you forget --recurse-submodules during cloning, don't worry! You can initialize and update them manually after cloning the parent repository.

First, navigate into the cloned parent repository.

After initializing, you need to tell Git to fetch the actual content for each submodule. This is done with the git submodule update command.

It fetches the data from the submodule's remote and checks out the specific commit recorded by the parent repository.

You've just cloned a repository named parent-repo which is known to contain a submodule. After cloning with just git clone parent-repo.git, what are the necessary commands to get the submodule's content ready for use?

In this lesson, you learned how to:

• Add a submodule using git submodule add <url> <path>, which creates a .gitmodules file and stages the submodule.
• Commit submodule changes to record the specific version of the submodule in the parent repository.
• Clone a repository with submodules using git clone --recurse-submodules for an all-in-one operation.
• Manually initialize and update submodules with git submodule init and git submodule update if you cloned without the recurse flag.

Next, we'll explore how to manage and update submodules after they've been added and cloned.