Setting Submodule
Overview of Configuring a Submodule
A submodule is a Git tool used to manage shared repositories for higher team efficiency. Submodules allow you to keep a shared repository as a subdirectory of your repository. You can isolate and reuse repositories, and pull latest changes from or push commits to shared repositories.
When the repository Test_Fir needs to contain and use the repository Test_Sec (a third-party library or a library developed for multiple parent projects), and you want to treat them as two independent projects and want to use Test_Sec in Test_Fir, you can use the submodule function of Git. Submodules allow you to use a Git repo as a subdirectory of another Git repo. This means that you can clone another repo into your own repo while keeping commits independent.
The submodules are recorded in a file named .gitmodules, which records the information about the submodules.
[submodule "module_name"] # Submodule name path = file_path # File path of the submodule in the current repository (parent repository) url = repo_url # Remote repository IP address of the submodule (sub-repository)
In this case, the source code in the file_path directory is obtained from repo_url.
Constraints
If the content of the Test_Fir repository will be used as a submodule of the Test_Sec repository, you need to have both the set and code commit permissions for the Test_Sec repository. For details, refer to Configuring Repo-Level Permissions.
Adding a Submodule on the Repo Page
You can add a submodule with any of the following methods as needed.
- Go to the repository homepage to which a submodule is to be added, and click Code, as shown in the following figure. Click the
button, select Create Submodule, and set parameters by referring to the table.
- Go to the repository homepage to which a submodule is to be added, and click Code, as shown in the following figure. Click the
button, select Create Submodule, and set parameters by referring to the table.
- Access the repository homepage to which a submodule is to be added, choose Settings > Repository Management > Submodules on the top menu bar, click Create Submodule, and set parameters by referring to the following table.
Configure the following parameters and click OK. After the creation is complete, you can find the submodule (child repository) in the corresponding directory of the repository file list. The icon on the left of the corresponding file is
.
Table 1 Parameters of creating a submodule Parameter
Description
Submodule Repo Path
You need to select a repository as the subrepository, which can come from a different project.
Submodule Repo Branch
Select the target branch of the submodule to be synchronized to the parent repository.
Submodule File Path
Configure the path of the submodule file in the repository. Use / to separate levels.
Commit Message
Remarks for creating a submodule. You can find the operation in the file history. The value contains a maximum of 2,000 characters.
Adding a Submodule on Git
- Run the following command to add a submodule:
git submodule add <repo> [<dir>] [-b <branch>] [<path>]
- <repo> indicates the remote repository address of the submodule to be added.
- [<dir>] (optional) specifies the name of the directory for storing the cloned submodule. If this parameter is not specified, Git automatically infers a name based on the repository URL.
- [-b <branch>] (optional) specifies the branch to check out the code from. If this parameter is not specified, the code will be checked out from the default branch by default.
- [<path>] (optional) indicates the path recorded in the .gitmodules file of the parent project. If this parameter is not specified, the value of <dir> is used by default.
For example, run the following command to embed the WEB-INF.git repository as an independent subproject into the current Git project:
git submodule add git@example.com:****/WEB-INF.git
- Run the following command to pull the repository that contains submodules, that is, to clone a Git repository that contains submodules and automatically initialize and pull the submodule content:
git clone <repo> [<dir>] --recursive
- git clone <repo> indicates that the specified Git repository is cloned to the local host, and <repo> indicates the URL of the remote repository to be cloned.
- [<dir>] (optional) indicates the local directory where the cloned repository is saved. If this parameter is not specified, the repository name is used as the directory name by default.
- --recursive indicates that after the cloning is complete, Git automatically initializes and updates the content of all submodules.
For example, run the following command to clone a Git repository named WEB-INF from the remote repository to the local host. If the WEB-INF repository has submodules, all submodules are recursively cloned.
git clone git@example.com:****/WEB-INF.git --recursive
- Run the following command to pull the latest commit from the remote repository of the submodule (origin or user-configured remote one) and update the submodule code to the latest commit (usually the latest commit of the default remote branch, for example, main or master). This update does not automatically merge or modify the code of the parent repository. It only updates the reference of the submodule.
git submodule update --remote
- Run the following command to push the update to the submodule:
git push --recurse-submodules=check
- Run the following commands in sequence to delete the submodule:
- Delete the entry of a submodule from the .gitsubmodule file.
- Delete the entry of a submodule from the .git/config file.
- Run the following command to delete the folder of the submodule.
git rm --cached {submodule_path}
When entering the path, delete the slash (/) at the end.
For example, if your submodule is stored in the src/main/webapp/WEB-INF/ directory, run the following command:
git rm --cached src/main/webapp/WEB-INF
Editing a Submodule
You can edit a submodule if you have the set permission on the repository. For details, see Configuring Repo-Level Permissions.
As shown in the following figure, Submodule Repo Path indicates the Git address of the sub-repository. You can click Commit ID to view the historical commits of the sub-repository.
Click in the Deploy Key Synchronization column to synchronize the deploy key of the parent repository to the child repository. The child repository will inherit the deploy key of the parent repository.
If the Submodule Test Result column shows Exist, it indicates that the sub-repository is available. To delete the submodule, click in the Operation column.

Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot