One of the most powerful things that most developers hold high is efficiency on the resources and the development cycle.
When it comes to git, we encounter instances where we can intergrate code and reuse code from other repositories. However, it can be challenging attempting to merge code customizations with upstream changes. This is where git submodules come into play.
What is Git Submodule?
In git, a submodule is a feature that allows us to include a separate git repository within another Git repository as a single project.
Once incorporated, a submodule will act like a subdirectory within the main project but the the code of the subdule is not directly copied into the main repo.
By using submodulel, git will create a reference to the submodule's repository and place it inside the main repo.
An example of a git submodule is the tutanota repository. In the lib directory, you will find the webassembly repo which is a submodule.
https://github.com/tutao/tutanota/tree/master/libs/webassembly
Basic Git Submodule Commands
One of the most powerful things about git version control is the exceptional CLI tools that allow us to work with various features in the vcs.
In git, we can interact with submodules by using the git submodule commands. You can also use the git su bmodule to create, update, and manage submodules.
Let us explore some common git submodule commands and how to use them.
git submodule add
The first and most common command is the git submodule add command which allows us to add a submodule to given repository.
Start by navigating into the repo in which you wish to add the repository:
cd /path/to/repository
Next, use the git submodule add command followed by the URL of the submodule you wish to add. For example, suppose we want to include cpython in our repo, we can use the command:
git submodule add https://github.com/python/cpython
This should clone the cpython repository and include it in the repository as shown in the output:
You can also specify the path and name of the directory in which you wish to store the submodule. The command syntax is as shown:
git submodule add [url] [path]
For example, suppose we wish to store the submodule in the /deps/py directory, we can run the command as shown:
git submodule add https://github.com/python/cpython deps/py/cpython
By default, git will use the specified repository name.
git submodule init
The second command we will look at is the git submodule init command.
When we are cloning a repository that contains submodules, we must ensure to initalize the submodules using the git submodule init command.
git submodule init
To initalize a specific module, you can specify the submodule path as shown in the syntax below:
git submodule init [path]
git submodule update
The git submodule update command allows us to update the status of the submodules in a given repository. The comamnd syntax is as shown:
git submodule update
The command will clone the missing submodules, download any new commits, and updates the repo directory tree.
We can also add the --init flag to the update command to remove the need for running the git submodule init command.
Using the --recursive option also tells the command to check the submodules for any nested submodules and download them as well.
git submodule status
Next, we have the status command which allows us to find the status of a submodule. The command syntax is as shown:
git submodule status
An example:
The command should return a SHA-1 hash and the path of each submodule within the repository.
The SHA-1 string can have three different prefixes.
- The - prefix marks an uninitialized submodule.
- The
+sign shows that the checked-out submodule commit differs from the state of the original submodule repository. - The
Uprefix alerts to merge conflicts.
NOTE: Having no prefix in the SHA-1 denotes that teh submodule is initialized, synced with origin, and no conflicts.
git submodule deinit
The git submodule deinit command allows us to unregister a submodule. The command synyax is as shown:
git submodule deinit [path]
Git will remove the content of the submodule directory and deletes the entry in .git/config file that pertains to the specified submodule.
You can also deregister a submodule that contains local changes by using the --force option.
git submodule deinit [path] --force
Ths will discard the changes from the submodule.
git submodule foreach
This command allows us to execute a command on each submodule. The command syntax is as shown:
git submodule foreach [command]
For exmaple, suppose we wish to run the command git fetch on each submodule, we can use the command:
git submodule foreach 'git fetch'
Output:
Conclusion
In this comprehensive guide, we learned about the git submodules and the commands that we can use to work with submodules in a given repository.
