[QUICK-TIP] Git Submodules

In Git, a submodule is like a Git repository inside another Git repository. This can be useful for splitting work, or for including someone else's code within your project dynamically.

As an example, see the DuckDuckGo Android App and the corresponding .gitmodules file.

Quick Start

It's simple to add a submodule into your repository, with the following line:

git submodule add https://github.com/<user>/<repo> <path/to/save/at>

This will add a new file named .gitmodules within your projects root, that included the path to the source repo, along with the destination of where within your project it should be mapped to.

Note that to clone a repository along with it's sub modules, you must use the --recursive option. Similarly, to update the code within the submodules, you will need to run git submodule update --init --recursive.

For example, here (in my .gitmodules) I am adding the dotbot repo into the root of my dotfiles project:

[submodule ".dotbot"]
    path = .dotbot
    url = https://github.com/anishathalye/dotbot

Problems with Submodules

It's worth nothing, that this may work well for simple use cases, but would not be practical at all for referencing multiple packages. Usually a dependency management system (such as Cargo, NPM, RubyGems, Go Modules etc.) is a better solution.

Git doesn't automatically download submodules after clone (unless you use the --recursive flag), so if this is required for the project to run, you'll need to either document this, or add something into your build script to grab the submodules. Same goes for updates- submodules will not be fetched with a git pull, so git submodule update needs to be run.

There are also the potential security and stability issues this could cause, if you do not manage the repo being included. All in all, submodules are awesome, but for only a very particular use case.

Further Links

Example: https://github.com/duckduckgo/Android/tree/develop/submodules
Git Documentation: https://git-scm.com/book/en/v2/Git-Tools-Submodules
Git Module File Documentation: https://www.git-scm.com/docs/gitmodules
Git Submodule Documentation: http://www.git-scm.com/docs/git-submodule
GitModules File Documentation: https://www.git-scm.com/docs/gitmodules
GitHub Modules: https://github.blog/2016-02-01-working-with-submodules