Updated on 2023-07-25 GMT+08:00

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

  1. Add a submodule.

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

    Example:

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

  2. Pulling a repository that contains a submodule

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

    Example:

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

  3. Update a submodule based on the latest remote commit

    git submodule update --remote

  4. Push updates to a submodule.

    git push --recurse-submodules=check

  5. 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