Technical viewpoint: Submodules in Git¶

It is common while working on a project to need to iuse another project from within it. For example there is a library developed by a third party or the project development is the responsibility of several programmers and the work is done separately. In these situations there is a need for two separate projects while still having the ability to use one from within the other.

This issue is addressed in Git with submodules. Submodules allow keeping one Git repository as a subdirectory of another Git repository. This way you can clone another repository into your project while keeping the commit histories clean and separate.

Submodules in Practice¶

You can add a submodule into your repository with git submodule add URL. On this course this is already done. It is worth to note that this creates a new file .gitmodules. This file stores the information on how the repositories map and is version controlled.

Cloning a Project with Submodules¶

When cloning a project (e.g. your project repository) with a submodule in it, you do not get the contents of the submodule, only the directory. In order to get the files, you need to run two commands git submodule init and git submodule update. The first initializes you local configuration file and the second fetches the contents of the submodule. For example:

git clone https://course-gitlab.tuni.fi/esim.git
git submodule init
git submodule update

An easier and recommended way is to use --recurse-submodules when cloning to initialize and update automatically, i.e.

git clone --recurse-submodules https://course-gitlab.tuni.fi/esim.git

Submodules and Working on the Project¶

As the work progresses new work needs to be updates from the submodule. This is done with

git submodule update --remote

Doing this does not allow updating the submodule from your own project. However, on the course there is no need to be able to do that.

More Information¶

You can read more on submodules in the Git book. The documentation is available in: https://git-scm.com/docs/git-submodule.