NuGrid website

View My GitHub Profile

Distributed Version Control

This page describes resources that users need to use the NuGrid distributed version control facilities. It starts with information on git that is used for active developement. For archival access to the NuGrid svn server see bottom of this document.


Quickstart guide

Access with your browser

Command line access:

Resources to adopt github

Useful commands

Using Git Submodules

The purpose of git submodules is to create a version controlled link between the repository and git repositories that it depends on. When a repository is linked as a submodule the relative path to the submodule in the repository and the URL of the submodules remote is stored in the version controlled file “.gitmodule” if a specific branch to be tracked is specified it will also be stored in the “.gitmodule” file. When the submodule is linked and updated the result is a git repository nested with in your main git repository. NOTE: since the submodules are nested git repositories if your current working directory is in submodule any git command will act on the submodule and not the main git repository.

Adding a Submodule

To add a new submodule to the current repository use the command,

git submodule add <URL>

This will create the file “.gitmodule” in the root directory of the repository if the file does not exist already and it will create a directory containing a clone of the master branch from the repo at the URL. The path to where the submodule should be created can be specified using the command

git submodule add <URL> <PATH>

By default the submodule pulls commits from the master branch of the submodule’s remote. A branch other than master can be tracked by using the flag “-b ", the command to link a submodule tracking a branch other than master is then,

git submodule add -b <branch> <URL> <PATH>

Once the submodule has been added the submodule repository will be cloned into the specified path. NOTE: the submodule links to a specific commit on a branch not the branch itself; spesifying the branch tells git which branch to pull from when updating to the newest commit on the submodule’s remote. So when someone clones the repository the their submodule will point to the same commit even if that commit is behind the branch’s HEAD. This guarantees that a given commit of the main repository will always point to the same commit of the submodule unless it has been manually updated after being checked out.

Cloning a the Project

When cloning a repository by default the contents of the submodule are not fetched since they are tracked by a different repository. The simplest way to clone a repository with submodules is to tell the clone command to recursively clone the repository using the flag “–recursive”. The command is,

git clone --recursive <URL>

If the repository is not cloned recursively the submodules can be checked out using the commands,

git submodule init
git submodule update


git submodule update --init

In either case git processes two steps. First the submodules are initialized, the information about the submodule’s URL, PATH and BRANCH is updated in the main repositories “.git” files. Then the HEAD commit from the specified branch is checked out into the submodule’s PATH.

Whether you clone recursively or update the submodules manually, in either case git will checkout the latest commit in the specified branch not the branch itself. So when updated the contents of the submodule will be updated but in the detached HEAD state.

Updating submodules

Commands that update the main repository by default will not update the contents of the submodules. To update all of the submodules to the commit specified by the main repository use the command,

git submodule update

But if you would like to update the submodules to the latest commit on the submodule’s remote in the branch that it is tracking, then use the command

git submodule update --remote

If this change is committed then that commit of the main repository will point to the updated commit of the submodule. Alternatively if you navigate to the submodule’s directory you can checkout any commit which can then be applied to the main repository in the same manner.

Branching with submodules

If you switch to a branch that contains the same submodules pointing to the same commits of the submodules, then using submodules will have no side effects. However if you switch to a branch with different submodules from the current branch there are two side effects. First, any submodules that are not in the new branch will be left as untracked files after checking out the new branch. Second, any submodules that where not in the old branch will not be checked out after the branch is checked out, so you will need to call the command git submodule update so the submodule is checked out. If you switch to a branch with the same submodules but which point to different commits then you will need to call the command git submodule update to get the correct version.

Example of Submodules

There is an example use of git Submodules in the repository under the lsiemens_banch branch.

Useful tools

Graphical tools



NuGrid maintains a svn server at Keele. It is for members only. As we transition to NuGrid GitHub organization content will be deleted from the svn. Use of svn for active projects is at this point not supported and strongly discouraged (i.e. don’t do it).

Resources for svn