How to Use git submodule init

Introduction

When a user clones a Git project that contains submodules, Git does not check out the submodule content automatically. Instead, the submodule directories remain empty and require initialization and updating before becoming fully functional.

Submodule initialization is performed using the git submodule init command. The command adds relevant entries to the local Git configuration file and allows the user to run git submodule update and obtain the contents of the submodules.

This tutorial shows you how to use the git submodule init command and provides the most common usage examples.

Prerequisites

• Git installed.
• Access to Git repositories (for example, on GitHub).

Git Submodule init Syntax

git submodule init is a straightforward command that performs a single path recording task. Run it by using the syntax below:

git submodule init -- [path1​] [path2..]

The double-dash (--) sign is an optional divider between the command and the directory paths. It is possible to run the command without it:

git submodule init [path1] [path2...]

Git submodule init Examples

git submodule init copies the submodule information from the .gitmodules file to .git/config. Use it to:

• Initialize all submodules within a repository.
• Initialize only specific submodules, leaving others uninitialized.

The following sections provide practical examples of using the git submodule init command.

Initialize All Submodules

If you execute the command without providing directory paths, it initializes all the submodules present in the repository:

git submodule init

The output confirms that the command registered paths for all the repository submodules.

Initialize Specific Submodules

To initialize only specific submodules, list their paths after the command. The example below shows the contents of the .gitmodules file for the marko-pnap/test-repo repository.

The file shows two registered submodules in this repository, sample-submodule and second-submodule. Initialize only the sample-submodule by typing:

git submodule init sample-submodule

git submodule init sample-submodule/nested-submodule

Executing git submodule update after the above command fetches only the content of sample-submodule. The second-submodule directory remains uninitialized and empty. The ability to choose which submodules to initialize allows users to work and receive updates only from the submodules relevant for the particular task.

Edit Submodule Locations

git submodule init creates a record about submodules in the .git/config file, but does not check out the contents of the submodule repositories. A common scenario taking advantage of this behavior is when the user wants to edit submodule URLs before the checkout.

The screenshot below shows the contents of the .git/config file for test-repo after submodule initialization.

To change the URL of the submodule repository, edit the URL line in the section of the relevant submodule. The example below changes the URL of second-submodule to point to the third-submodule repository.

Performing git submodule update after making the edits above populates the second-submodule directory with the contents of the third-submodule repository.

Initialize Submodules with git submodule update

If you do not need to edit the submodule locations in .git/config, you can omit the git submodule init command and perform initialization by adding the --init flag to the git submodule update command:

git submodule update --init

The --init flag is often followed by --recursive to ensure that Git also updates nested submodules.

Conclusion

After reading this tutorial, you should know how to use the git submodule init command to initialize submodules in a Git repository.

To learn more about Git submodules, read Git Submodule Guide & Basic Commands to Get Started. For a comprehensive introduction to Git, refer to How to Use Git.