Git submodule tutorial

Fiji is hosted on a main git repository which contains several declared submodules such as VIB and TrakEM2.

With git, any git command executed within any subdirectory of the repository affects the overall git repository.

Submodules, although existing as folders inside the fiji repository, are different: only the folder name, as a path pointer, is registered as belonging to fiji's git repository, together with the current revision ("commit name", i.e. that 40-digit hex string which is the unique identifier of each commit) of that submodule.

Each submodule is a proper full-fledged git repository, so any git commands executed within the folders of the submodule will affect that git repository, not fiji's.

The usual sequence of commands when working inside a submodule:

~/fiji$ cd TrakEM2
~/fiji/TrakEM2$ git status

Say you observe some unstaged changes. Just add and commit them:

~/fiji/TrakEM2$ git add path/to/some_file.java
~/fiji/TrakEM2$ git commit

You can work as much as you like inside the submodule, and if you have something you want to commit to Fiji, the superproject, first make sure you pushed the changes of the submodule!

Then move up and add the current revision of the submodule inside fiji.

~/fiji/TrakEM2$ git push
~/fiji/TrakEM2$ cd ..
~/fiji$ git add TrakEM2
~/fiji$ git commit

BE CAREFUL: adding "TrakEM" and "TrakEM/" is not the same at all! The latter would add all non-ignorable files under TrakEM2's subfolder into fiji's repository, which is NOT what you want. If you screwed up, use "git reset --hard" before proceeding to unstage any changes in fiji's git repository.

After the above, fiji has been updated to track the latest TrakEM2 commit.

When happy with the arrangement, push the changes to the shared repository for others to see them. Remember to push both separately: the submodule and fiji's repository itself! If you push only fiji, then whoever pulls fiji will not see the new HEAD of the submodule branch, which will result in an error.

~/fiji$ cd TrakEM2/
~/fiji/TrakEM2$ git push
~/fiji/TrakEM2$ cd ..
~/fiji$ git push