TL;DR: A Git Submodule is, basically, a Git repository inside a Git repository.
What is a Git Submodule?
A Git Submodule is a folder (Git repository) inside a main Git repository. There can be more than one Git modules inside a parent Git repository and once created they are managed (pull, commit, push, etc.) independently from the parent Git repository . All Git submodules are defined in a .gitmodules file, that is located at the root of the parent repository.
NOTE: There’s a similar option in GIT, called Subtree Merging. Maybe, it is better suited to your situation.
What is it good for?
There are many reason to have a Git submodule as part of your main Git repository. Here are a few examples:
- Avoiding Code Duplication – If there’s a code that is used in more than one project, it can be managed in a separate repository and used as a submodule in each relevant project repository.
- External Libraries or Frameworks – If your code depends on an external library (or framework), submoduling the external library’s repository, will give you access to that library without incorporating it into your own repository. It, also, allows you to updated the submodule when needed to pull new updates to the library’s code.
- Shared Scripts Repository – If you need to use the same scripts in a Jenkins build job across several different jobs, a submodule can be useful for this purpose.
Some basic commands
Here are some basic commands to get you started.
Adding a submodule to an exciting repository
$ git submodule add https://github.com/<user>/repo_name folder_name
This will create a new folder called folder_name for the submodule and, depending on how advanced your Git version, clone and pull the repository into the folder defined in the git command.
Cloning a Main repository that has submodules in it
$ git clone --recurse-submodules https://github.com/<user>/MainProject
This will clone the main repository and initialize and update all submodules (and nested submodules).
Pulling changes from the Remote Project
$ git pull --recurse-submodules
This will make Git run git submodule update right after the pull, putting the submodules in the correct state.
Running a command on each of the submodules
$ git submodule foreach 'git checkout -b featureA'
This will create a new branch in all submodules.
Working with submodules requires constant thinking about their state. Many actions require special consideration and paying attention to the state of the submodules. Many of the actions performed on the main repository do not get performed on the submodules automatically and require the use of the –recurse-submodules option or other command options. You can read all about it in the two links at the top.