How to Use git submodule init

September 28, 2022


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.

Was this article helpful?
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
Git Submodule Guide & Basic Commands to Get Started
September 1, 2022

This guide will show you how to work with Git submodules and provide a list of the most frequently used commands and their options.
Read more
Add, Update, and Remove Git Submodule
September 22, 2022

Submodules help manage complex projects in Git. They allow external repositories to exist as directories within another repository, which makes it easier to maintain...
Read more
How to Perform Git Submodule Checkout
September 7, 2022

In this tutorial, you will learn how to obtain the contents of a submodule using the command line and how to automate the checkout process with GitHub actions.
Read more
Git Tag: An Overview of the Basic Functions
September 6, 2022

Git tags mark program release versions, bug fixes, patches, or specific commits. This tutorial provides an overview of basic Git tag actions.
Read more