Submodules are just normal Git repositories. However, they are cloned into a subdirectory of another project. This makes Submodules an ideal tool to keep external libraries cleanly separated from your own code.

Submodules in Tower

Tower's sidebar lists all of your project's Submodules.

  • The configuration of a Submodule can be inspected and changed in its detail view, after selecting it in the sidebar.
  • The actions that can be performed on / with a Submodule are available via its right-click menu.

How Git Submodules Work

Understanding how Submodules work in general is key to using them anywhere - on the command line or in Tower.

Just normal Git repositories

Submodules are really just standard Git repositories. You can modify, commit, pull, push, etc. from inside it like with any other repository.

Actual contents are not stored

The actual contents of a Submodule are NOT stored in its parent repository. Only its URL, the local path inside the main project and the checked out revision are stored by the main repository.

To be more precise: a Submodule's .git repository folder is placed in the main project's .git/modules folder; only the Submodule's working files are placed inside the specified directory in your project - but they are not version controlled in the main project.

Commits, not branches are checked out

Submodules always point to a specific commit - not a branch. Since the contents of a branch can change over time, as new commits arrive. Pointing at a specific revision, on the other hand, guarantees that the correct code is always present.