How to use git submodules

Adi Gherman

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.


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.


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.

git submodule add repoA 
git submodule add repoB
git commit -m "added repoA and repoB as submodules"
git push

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


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

Step 5 - update repoAB submodules

And now we can update repoAB.

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