Skip to content

Add note about using --recurse-submodules

Adam Cohen requested to merge update-submodule-docs into master

What does this MR do?

This MR adds a note about using the --recurse-submodules flag for the git checkout command:

Using the --recurse-submodules flag of git checkout can also be useful when you work on several branches in the superproject, each having your submodule pointing at different commits. Indeed, if you switch between branches that record the submodule at different commits, upon executing git status the submodule will appear as “modified”, and indicate “new commits”. That is because the submodule state is by default not carried over when switching branches.

This is the case if you work on gemnasium-maven or gemnasium-python. For example, let's assume you're on the master branch of gemnasium-maven, and want to check out another branch called some-other-branch. If you checkout this branch, you'll receive a message that the gemnasium submodule has changed:

$ git co some-other-branch

M	gemnasium
Switched to branch 'some-other-branch'
Your branch is up to date with 'origin/some-other-branch'.

$ git diff

diff --git a/gemnasium b/gemnasium
index 9d5c6f9..e51d1ee 160000
--- a/gemnasium
+++ b/gemnasium
@@ -1 +1 @@
-Subproject commit 9d5c6f94ac811574db3375a067d2127e82fea29b
+Subproject commit e51d1ee2af125183d606bd4c43073d043b94c925

This can cause an issue if you were to commit changes on some-other-branch, since it would also have the unintended consequence of updating the gemnasium submodule.

This can be fixed by using the --recurse-submodules flag when using git checkout. A git alias can be created to handle this automatically by using the following command:

git config --global alias.co 'checkout --recurse-submodules'

What are the relevant issue numbers?

Does this MR meet the acceptance criteria?

Merge request reports