Submodules are an useful way to be able to integrate reusable libraries and component within your project. Indeed it's possible to tell git to also fetch and check-out in some folder of your repository another repository in a specific version ( e.g. You need the library a with version 1.0.0 ) or branch.

Submodules are really useful when you work on a reusable component as well as on a software using this comoponent, this way you have code of both in the hand and can edit them together but commit them separately, so that other projects also benefits from the changes.

• Creating submodules : choosing whether relative or full url
• Creating submodule following a particular version
• Creating submodules following a given branch

Creating submodules : choosing whether relative or full url

Submodules can be created with full or absolute URL to repositories to reference. The choice of the right type depends on your needs.

• Relative URL ( e.g. ../related-repo-in-same-organization.git ) are useful when you want to group repositories which are part of the same project and which are likely to be edited along the others aside them by the same team.

  • It is so because when someone will fork the repository, he will need to fork also the related submodules.

• Full URL ( e.g. https://github.ch.sauter-bc.com/SomeOtherOrganization/a-repo-i-use-but-that-im-not-responsible-of.git ) when you want to reference repositories that are not under your responsibilities and that you plan to only edit or eventually make really small patch for it ( i.e. A bug fix and that's it)

  • It clearly shows it's an external dependency which isn't under your responsibility, but under the one of another team.

Creating submodule following a particular version

This is useful, when you don't need the sources of the submodule to edit them, but more to have them for reference or for the sake of your build. Usually you would do this for full url repositories.

Command line example

Create a submodule to reference Boost 1.55.0

# create a folder libs/boost with the content of the lib-cpp-boost in it
git submodule add -b branch-containing-the-version https://github.ch.sauter-bc.com/External/lib-cpp-boost.git libs/boost

# select the right version
cd libs/boost
git checkout v1.55.0

# add the reference to the version selected to the repository referencing the submodule
cd -
git add libs/boost 
git commit -m "SUBMODULE: Added boost 1.55 as reference."

SourceTree example

Create a submodule to reference the current commit of Case-Suite-Deployment.
This submodule will always follow the (fixed) version of this particular commit until you manually update it.

1. Add a new submodule choosing "Repository/Add Submodule"

   Add the url of the repository containing the desired submodule.
   The local relative path will be inserted automatically, you can edit it.

2. Now you will find a new submodule entry in your tree and also some new entries in the .gitmodules-file.

   This submodule will

3. If you use the Visual Studio environment to build your applications, you have to add this new submodule to your solution. If this is the first submodule in your solution, you should firstly add a new folder. In the following example it is called "CASE-Suite-Submodules".
   Now you can add this submodule using "Add/Existing Project" in the context menu of the submodules folder:

   

   ...and select the desired project-file:

   

   Do not forget to delete the existing dll from your application (the one which is now built by the submodule) and change the reference-path of the referenced dll in your application.

Update submodules day after day

Then to work all days with

git pull origin master --recursive

Creating submodules following a given branch

Following some branch is needed usually when you use relative url for a submodule to some repository because it's developped in the same time than your current project and need to be able to change alot of things within the submodules. Or eventually when you want always the latest version of some repository.

Command line example

In a repository for a server application, you create a submodule to reference the develop branch of application-client which is developed and needs to be changed as you change the server interface.

# create a folder client/ alongside the server source code which follows the develop branch
git submodule add -b develop ../application-client.git client/ 

# add a configuration so that updates fetched from remote get merged as when you pull your repo
git config -f .gitmodules submodule.application-client.update merge

# add the reference to the branch selected to the repository referencing the submodule
git add .gitmodules
git add client
git commit -m "SUBMODULE: Added client app to follow the develop branch"

Update submodules day after day

First time

git pull origin develop
git submodule update --init --remote --recursive
cd path/to/submodule/ && git checkout develop

Then to work all days with

git pull origin develop
git submodule update --init --remote --recursive