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 sub-repository
Parameter	Description
Submodule	Select a repository as the submodule.
Submodule Branch	Select the target branch of the submodule to be synchronized to the parent repository.
Submodule Path	The storage path of the sub-repository in the parent repository. Use slashes (/) 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 (sub-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
```