GitHub Tutorial to Manage Project with SubRepositories

Overview:

This guide tells you how to create a repository that is composed by sub-repositories (submodules). This is convenient while working on large projects in ROS to collect in a single repository several independent packages that are being used together. Hence, avoiding to download each repository singularly and ensuring a tested and stable version is used.

Usually the parent repository (the project) should contain the documentation, ROS launchers and a link to each submodule repository. This link is a static snapshot and it is set during project creation. Nevertheless, you can update this link during project cloning.

Create a Project as a collection of subprojects

To create a new project in Github:

• Create a new repository from web

• Clone this (empty) repository to you machine:

    git clone <https://github.com/proj>
  

• You can add a subrepository by typing:

    git submodule add -b <branch_name> <https://github.com/submodul/rep1>
  

Repeat for all desired submodules.

• Push those changes:

    git commit -m "comment"
    git push origin master
  

Clone the Project

To clone and update your project on your machine:

• Clone the project:

    git clone <https://github.com/proj>
  

• Go into the project folder:

    cd proj
  

• Initialize all submodules:

    git submodule update --init --recursive --remote
  

• Update all files and checkout to a specific branch (e.g., master):

    git submodule foreach git pull origin master
    git submodule foreach git checkout master
  

Modifying submodules

Every time you want to change something inside a submodule, do it in its original repository in order to have consistent commit and push. Then update the snapshot in your parent project using:

	git submodule foreach git push origin master
	git submodule foreach git checkout master

This is useful also if you depend on a third-party submodule and you want to update your project to a newer version.