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, 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	Mandatory. Select a repository as the sub-repository. You can select a cross-project repository.
Submodule Repo Branch	Mandatory. Select the target branch of the submodule to be synchronized to the parent repository.
Submodule File Path	Mandatory. 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

Add a submodule.

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

Example:

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

Pull 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
```

Editing a Submodule

You must have the set permission to edit submodules. 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.