What is a submodule in GIT and how to add, update and remove a submodule?

Learn How to add a code from another repository?

While using git, you’ll notice that a project may contain multiple folders. Each folder can be another project itself. However, they are all under the same repository URL.

For instance, there might be the main application folder having code for connecting to a remote IP machine via socket, along with subfolders for UDP, TCP, and SCTP for each socket type.

Besides that, a required project can be hosted at another git repository URL. It could contain code for third-party libraries that must be included in your project, or it could contain some other useful code.

Submodules in git are a convenient way to refer to other remote projects within your project

Table Of Contents
  1. What is a submodule in git?
  2. How to add a git submodule in the main project?
  3. How to clone submodules?
  4. How to update submodules?
  5. How to remove the submodules in git?

In this tutorial, we will discuss what is a submodule and how to add, remove and update submodules in your working project.

What is a submodule in git?

Submodules are references to code sources stored at remote repositories. Additionally, when you clone the main project, you can clone all the included submodules. This eliminates the manual work required to keep all third-party software updated.

How to add, remove or update a submodule?

To demonstrate we have two repositories one for the main project and another for the third party. With examples, we will show, how to add the third-party git project as a submodule in the main project with the command line.

ProjectURL
Main Project https://github.com/cspsprotocol/projectsource.git
Third-Party https://github.com/cspsprotocol/third-party.git

How to add a git submodule in the main project?

This is the initial step. To add a submodule, run the git submodule add command, passing the URL of the submodule repository and the optional name of the directory that will contain the submodule code. If no folder name is specified, the repository name will be used.

git submodule add https://github.com/cspsprotocol/third-party.git
Cloning into 'third-party'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.

A submodule is added to the stage just like any other resource. Need to commit and push for future usage.

 git commit -m" Added submodule third-party"
 git push

How to clone a git submodule?

By default, cloning a repository does not bring the code for a submodule. Although empty folders are created for each submodule. You may use the option to fetch the code of submodules at the time of clone or later.

Use a -recurse-submodules option with the clone command to bring the code of submodules.

git clone --recurse-submodules  https://github.com/cspsprotocol/projectsource.git

How to update submodules?

Clone submodules later, using the git submodule update command with -recursive and -init command-line options. 

git submodule update  --recursive --init

How to remove the submodules in git?

The removal of a submodule in git is performed in the following steps.

  • Deinit the submodule (git submodule deinit <submodule-name>) – This is the first step that will remove the references (in .git/config file) of the submodule given in the command line.
  • Remove the folder – Use Linux delete directory command (rm). This will delete all files inside the folder along with the folder itself
  • Remove the directory for the next commit.
  • Commit the changes.
  • Push the code (git push command) – This will update the central repository.
git submodule deinit third-party
Cleared directory 'third-party'
Submodule 'third-party' (https://github.com/cspsprotocol/third-party.git) unregistered for path 'third-party'
rm -rf third-party/
git rm third-party
 
git commit -m"Removed the submodule third-party"
[master 0ad6683] Removed the submodule third-party
 Committer: root <root@localhost.localdomain>
git push

Counting objects: 3, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 234 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/cspsprotocol/projectsource.git
   f1ed01e..0ad6683  master -> master