How to use git submodules

Adi Gherman
2021-06-02

In this document I will describe how to use git submodules to create a central repository that will serve as a library for individual packages that share the same functionality.

By design, Neuroconductor will only accept packages that are individually hosted on GitHub and the folder structure follows our package preparation guidelines. If a maintainer has a package structured as a library of individual packages each stored in a subfolder, this package structure will not be properly processed by our Neuroconductor platform. So it is recommended that maintainers should keep the packages as individual repos and combine them into a central package using git submodules.

Step 1 - Select individual repositories

For this example, I've created 2 repositories each containing a single text file.

repoA
repoB

Step 2 - Create central repo to host repositories selected at Step 1

I'm creating a empty repository, repoAB that will serve as a central library repository for repoA and repoB.

repoAB

Step 3 - use git submodule to add repoA and repoB

Now it's time to add repoA and repoB as submodules to repoAB. This is done using the git submodule command.

On your local machine you need to clone the empty repoAB repository and then cd into it in order to issue git commands. Next, the two submodules will be added to this empty repository, followed by a commit and push commands.

submodules
git submodule add https://github.com/adigherman/repoA repoA 
git submodule add https://github.com/adigherman/repoB repoB
git commit -m "added repoA and repoB as submodules"
git push

This should add the submodules and now repoAB should look like this.

repoAB

Step 4 - modify any repo

Keeping the central repository repoAB up to date is an easy task. Let's first add another file to repoA.

second file
repoA_2

Step 5 - update repoAB submodules

And now we can update repoAB.

update
git submodule foreach git pull origin master
git commit -a -m "updated on 2019-04-30"
git push
repoAB_updated