Git submodules

Table of Contents

• Cloning parent and its submodules
• Cloning a particular submodule
• Making changes in submodules
  • Updating a submodule
  • Updating a submodule and its parent
• 'foreach' submodule

For getting started, continue with the documentation, but for an extensive explanation of how git submodules work, read this Git Submodules Tutorial

Cloning parent and its submodules

Cloning the parent repository in recursive will include all its submodules

git clone --recursive https://github.com/KnowledgeFinder/knowledgefinder-core.git

change to directory

cd knowledgefinder-core

Now load all the submodules,

git submodule update --init

The parent repository contains a file called .gitmodules, where it points to which branch does each submodule should be loaded. In our case, all the submodules will be pointing to master branch. Thus, the above command will load the submodules pointing to master branch. But, git submodules works in such a way that apart from branches, it also points to specific commits made in the branches the last time the parent repository is committed. Thus the above command will update submodules to the latest commit in parent repository, which may not necessarily be the latest commit in the submodules.

If there is a need to load the latest commit from all the submodules,

git submodule update --remote

Or, from a specific submodule,

git submodule update knowledgefinder-dataimport

It is not mandatory anyway, as at any given point of time, parent repository should point to a stable working version of all submodules.

Cloning a particular submodule

If one just wants to work with knowledgefinder-dataimport, there are two ways to do it:

• clone the parent repository and update just the dataimport repository

  git clone --recursive https://github.com/KnowledgeFinder/knowledgefinder-core.git
  cd knowledgefinder-core
  git submodule update knowledgefinder-dataimport

• clone the dataimport repository directly

  git clone https://github.com/KnowledgeFinder/knowledgefinder-dataimport.git

Making changes in submodules

This section is for developers who wish to contribute my making changes in the code. Users can skip this section. Let us consider knowledgefinder-core as the parent repository(with a .gitmodules file) and knowledgefinder-dataimport as the submodule(without a .gitmodules file). Thus knowledgefinder-dataimport will be called as submodule only when the parent repository is used. Otherwise it is just a normal git repository.

Updating a submodule

This method is fairly simple, just as a normal git repository. And its explained here mainly for comparison.

git clone https://github.com/KnowledgeFinder/knowledgefinder-dataimport.git
cd knowledgefinder-dataimport
git checkout develop
touch newfeature.md
git commit -m "new feature file added"
git push origin develop

Updating a submodule and its parent

Cloning a parent repository and updating all its submodules. This will pull all the submodules which .gitmodules file from the parent repository is pointing to (master in our case). Once a change is made in submodules, both the submodule as well as the parent repository shows uncommitted files .

> C:\....\knowledgefinder-core
cd knowledgefinder-dataimport
> C:\....\knowledgefinder-core\knowledgefinder-dataimport
git checkout develop
touch newfeature.md
git add newfeature.md
git commit -m "new feature file added"
git push origin develop
cd ..
> C:\....\knowledgefinder-core
git add knowledgefinder-dataimport
git commit -m "parent repo updated with newfeature.md in dataimport"
git push origin develop

⚠️

It is recommended to update the parent repository, if and only if the changes are working fine with all other submodules. Also the .gitmodules file present in the branch of parent repository in which you commit has to be taken care of. As it may point to some other branch in the submodules. Updating the parent repository is best left to Moderators.

'foreach' submodule

In order to apply a command to each submodule, use git submodule foreach command from the parent repository. For example to configure your git user-name in each repo,

git submodule foreach git config user.name xxxx