Submodules: when to use them?

A git submodule is a standard git tool that lets one Git repository include another repository at a fixed commit. In practice, this is useful when content is developed and reviewed in a separate repository, while the parent repository controls exactly which version is published.

When you add a submodule, Git records:

• the submodule URL and branch in .gitmodules

• the checked-out submodule commit in the parent repository index

When to use submodules¶

In some cases, e.g. for large Jupyter Books with many contributors, it may be useful to use submodules to organise the notebooks and other content elements. A nice example of this is the C3S training Jupyter Book which is a collection of notebooks covering many of the C3S data products. Many of these notebooks were produced by the data providers, and underwent a review process prior to publication in the main C3S training Jupyter Book. The submodule setup provided a staging Jupyter Book where notebooks could be published in a more realistic environment for the reviewers.

Submodule template¶

For more details on configuring a repository to be used as a submodule for an upstream Jupyter Book please see the Jupyter Book Submodule Template.