Git submodules are like repositories within repositories, which allow you to include external code libraries or dependencies in your project, all without linking the module’s version control to the project itself. This keeps modules separate and easy to update, and it’s easy to convert a directory into a new submodule.
What is a Submodule in Git?
A submodule is a Git repository that is embedded within another Git repository. This allows you to include code from another project as a dependency, while still maintaining its own version control.
When you clone the parent repository, it automatically clones the submodule repository as well. This means that the submodule’s code and Git history is kept separate from the main version control, and can be updated for multiple repositories that consume the library.
An alternative to submodules is to publish your libraries as packages to package managers like NPM, Maven, or NuGet. However, this doesn’t work for all types of projects, and if you’re working with private code, you’ll need to set up a private package registry, which can be more complicated than simply embedding the library’s source code as a submodule.
One of the main problems with turning an existing directory into a submodule is that the submodule should be managed externally. Git expects you to create a new empty directory for it, and clone the submodule into the project. You can copy the code to a new folder, but you will lose all the Git history related to it, which can be very detrimental in large projects. Instead, we’ll clone the repository, filter out the unneeded code, and push the new history to the new submodule.
How to Turn a Directory Into a Submodule
The first step is to create a new repository for the submodule. This is usually on a Git hosting service like GitHub, though you can create a local repository on your computer.
Next, you will want to get a fresh copy of your main repository to make the submodule repository from.
git clone git@github.com:username/repository.git submodule-repo cd submodule-repo
Next, you will want to filter out everything that isn’t related to your submodule. This will delete all the commit history that isn’t related to the code contained in the submodule. This is a destructive operation, so make sure you’re doing this on the copy of your repo, not the main one.
git filter-branch --subdirectory-filter submoduledirectory -- --all
You’ll be left with only the code that was in the directory, and only the commits pertaining to it. This will let you transfer over all the Git history related to that submodule.
You’ll want to change the remote URL of this module directory to your new submodule repository, which is typically named “origin.”
git remote set-url origin https://github.com/new-repository.git
Then, you can push the history as you normally would.
git push -u origin main
Adding a New Submodule
Back over in the main project, you will want to add the submodule.
First, you need to stop tracking the directory that you want to turn into a submodule from the parent repository. It will still be there in Git’s version history, and you just added it to the new module repository anyway.
rm -rf directory_name
Next, you can add the remote URL for the submodule repository that you created on Github, using the git submodule add command:
git submodule add git@github.com:username/repository.git directory_name
When you run this command, Git will create a new submodule directory in the parent repository, and it will clone the submodule repository into this directory. It will also start tracking the module folder again.
To update the submodule, you can use the git submodule update command:
git submodule update --remote submodule_name
