Working with GIT sub-modules

GIT Sub-modules are a powerful weapon in the hands of IT professionals working on large projects scattered in various repositories

Introduction

GIT sub-modules often incorporate another versioned project within an existing one. Sub-modules come in very handy when working on large projects and the modules of the project are scattered in different repositories due to technical and business reasons.

Sub-modules can be used for:

• To store the third-party library used in the main project
• To keep up with the changes made in the third-party library by other teams

Add a GIT sub-module

In order to add a GIT sub-module, use the "git submodule add" command, with the URL of the GIT remote repository to be included as a sub-module. Optionally one can specify the target directory. If the target directory parameter is not provided then the sub-module will be included in the directory named as the remote repository name.

git submodule add <REMOTE_REPOSITORY_URL> <TARGET_DIRECTORY>

On adding a new GIT sub-module in the project, the following changes will happen:

• A folder is created in the GIT repository named after the sub-module. The target directory name is mentioned in the "add" command in most scenarios.
• A hidden file named .gitmodules is created, this file contains the references to the remote repositories that are cloned as sub-modules
• The GIT configuration file (.git/config) is also modified in order to include the sub-modules just added.
• The sub-modules just added will be marked as changed to be committed in the repository.

As a consequence of the "add" command, one needs to commit a sub-module by using the "git commit" command.

git commit -m "New Sub-module is being added"
git push

PULL a GIT sub-module

Whenever someone is cloning a GIT repository with sub-modules, one needs to execute an additional command in order to fetch the contents of the sub-modules. If one does not execute this command, one will fetch the sub-module folder but not its content.

To pull a GIT sub-module, use the "git submodule update" command with "init" and "recursive" options.

git submodule update --init --recursive

The sub-module is always set to have its HEAD detached at a given commit by default, as the main repository is not tracking the changes of the sub-module, it only seems as a specific commit from the sub-module repository

UPDATE a GIT sub-module

In order to update an existing sub-module, one needs to execute the "git submodule update" command with "remote" and "merge" options

git submodule update --remote --merge

Using the "remote" option, one will be able to update existing GIT sub-modules without having to run "git pull" commands in each sub-module of the project.

REMOVE a GIT sub-module

In order to remove the GIT sub-module from the repository, use the "git submodule deinit" command

git submodule deinit <SUB-MODULE>
git rm <SUB-MODULE>

Execution of the above commands will have the following impact:

• Will delete the local sub-module configuration stored in the repository
• The sub-module referencing line will be deleted from the git configuration file
• The "git rm" command is used to delete the sub-modules files in the working directory and the remaining .git folders

Thanks :)

Happy sub-module 😄