What is a submodule in Git? How to add, update and remove it?

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 example, the main application has code for connecting to a remote IP machine via different types of network sockets and subfolders for UDP, TCP, and SCTP socket wrappers.

Additionally, a linked subproject can be hosted at a different git repository. The code may include code for third-party libraries that must be included in your project or some other useful code.

Table Of Contents
  1. Git submodule add.
  2. Git submodule clone.
  3. Git submodule update.
  4. Git submodule remove.

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

What is a submodule in Git?

Submodules in Git are convenient for referring to the other remote projects from your development line. You can clone all the included submodules when you clone the main project. This eliminates the manual work required to keep all third-party software updated.

To demonstrate, we have taken two git repositories, one for our project and another for a third-party library. The following examples show how to add, clone, update and remove the third-party submodule in the main project using the git commands.

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

Git submodule add.

The git submodule add command adds a module to the repository. It requires two arguments: the URL and the folder name (optional) containing the code of the submodule. In the absence of a folder name, the repository’s 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.

Submodules are added just like other resources. We need to commit and push for future usage.

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

Git submodule clone.

Submodule code is not automatically copied when cloning a repository. However, 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

Git submodule update.

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

git submodule update  --recursive --init

Git submodule remove.

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) to 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