Submodules

Background

A submodule is a Git tool used to manage shared repositories. It allows you to embed a shared repository as a subdirectory in a repository. You can isolate and reuse repositories, and pull latest changes from or push commits to shared repositories.

You may want to use project B (a third party repository, or a repository developed by yourself for multiple parent projects) in project A, and use them as two separate projects. Submodules allow you to clone a Git repository as a subdirectory into another Git repository while keeping commits separate.

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.

Using the Console

Creating a submodule

Entry 1:
You can add a submodule to a folder in the repository file list.

Click and select Create Submodule, as shown in the following figure.
Entry 2
You can create a submodule on the Code tab page

Click and select Create Submodule, as shown in the following figure.
Entry 3:
You can create a submodule in the repository settings.

Choose Settings > Repository Management > Submodules > Create Submodule.

Remarks:

You can use one of the preceding methods to create a submodule.

Configure the following parameters and click OK.

**Table 1** Parameters of creating a submodule
Parameter	Description
Submodule Repo Path	Select a repository as the submodule.
Submodule Repo Branch	Select the target branch of the submodule to be synchronized to the parent repository.
Submodule File Path	Path of the submodule file in the repository. Use / to separate levels.
Details	Remarks for creating a submodule. You can find the operation in the file history. The value contains a maximum of 2000 characters.

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 .

Viewing, synchronizing, and deleting a submodule
Choose Settings > Repository Management > Submodules. On the displayed page, repository administrators can view, synchronize, and delete submodules.

Synchronizing deploy keys
If a submodule is added on the Git client, the repository administrator needs to synchronize the deploy key of the parent repository to the submodule on the Settings > Repository Management > Submodules page. In this way, the submodule can also be pulled during the build of the parent repository.

Using the Git Client

Add a submodule.

git submodule add <repo> [<dir>] [-b <branch>] [<path>]

Example:

git submodule add git@***.***.com:****/WEB-INF.git

Pulling a repository that contains a submodule

git clone <repo> [<dir>] --recursive

Example:

git clone git@***.***.com:****/WEB-INF.git --recursive

Update a submodule based on the latest remote commit
```
git submodule update --remote
```
Push updates to a submodule.
```
git push --recurse-submodules=check
```
Delete a submodule.
1. Delete the entry of a submodule from the .gitsubmodule file.
2. Delete the entry of a submodule from the .git/config file.
3. Run the following command to delete the folder of the submodule.
```
git rm --cached {submodule_path} # Replace {submodule_path} with your submodule path.
```
  Omit the slash (/) at the end of the path.
  
  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
```