Updating a Submodule

Git remembers which exact revision of a Submodule repository you want in your main project. In fact, this information is part of version control: moving the pointer has to be committed like any other change, too.

Checking out this revision is referred to as "updating" the Submodule.

When to Update

A Submodule should be updated whenever its revision pointer was changed. This can happen after various operations:

  • checkout (when the other branch requires a different version of the Submodule - or none at all...)
  • merge / rebase (where the merged in revision changes the revision pointer)
  • reset...

Git on the command line doesn't perform an update automatically and only marks your Submodule as "modified". Tower helps make this easier with its "auto-update" feature.

Auto-Update in Tower

Whenever a Submodule's pointer has been moved after an operation, Tower will update the Submodule accordingly. This makes sure that the code in your Submodules is always at the revision it's supposed to be. If you should not want this behavior, you can simply switch it off in Tower's preferences.

Auto-Cleanup in Tower

Another helpful behavior is that Tower automatically cleans up obsolete Submodule code.

E.g., imagine switching from a branch that has a certain Submodule to a branch that doesn't have this Submodule. Git's default behavior is to simply leave the Submodule code as an untracked folder in your working copy - a very irritating side effect.

Tower helps in this situation by automatically cleaning up obsolute code from your working copy.

When Auto-Update is Not Possible
As described, Tower tries to automatically update or even clean up Submodules according to the current HEAD revision. However, this cannot be done in the following cases:
a) If the Submodule is dirty (contains uncommitted local changes), you need to open the Submodule and either commit these changes or discard them.
b) If the Submodule's pointer was moved, you need to make sure the new pointer was committed to the main project.