How to Use git submodule init

How to use git submodule init


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.

How to use git submodule init


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..]

Note: Execute git submodule init in the main repository directory.

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.

Output from git submodule init without no directory paths provided.

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 .gitmodules file showing the registered submodules in the 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
Initializing a specific submodule.

Note: To initialize specific nested submodules, enter their full path when executing the init command. For example, initialize nested-submodule inside sample-submodule by typing:

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.

Editing submodule URLs in the .git/config file.

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.

Editing a submodule entry in .git/config.

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
Initializing submodules using the --init flag with git submodule update.

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

Note: For a complete tutorial on pulling Git submodules to your local machine, read How to Pull the Latest Git Submodule.


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.

Đăng ký liền tay Nhận Ngay Bài Mới

Subscribe ngay

Cám ơn bạn đã đăng ký !

Lỗi đăng ký !

Add Comment

Click here to post a comment

Đăng ký liền tay
Nhận Ngay Bài Mới

Subscribe ngay

Cám ơn bạn đã đăng ký !

Lỗi đăng ký !