How do I move an existing Git submodule within a Git repository?

Question

I would like to change the directory name of a Git submodule in my Git superproject.

Lets suppose I have the following entry in my .gitmodules file:

Answer 1

The trick seems to be understanding that the .git directory for submodules are now kept in the master repository, under .git/modules, and each submodule has a .git file that points to it. This is the procedure you need now:

• Move the submodule to its new home.
• Edit the .git file in the submodule's working directory, and modify the path it contains so that it points to the right directory in the master repository's .git/modules directory.
• Enter the master repository's .git/modules directory, and find the directory corresponding to your submodule.
• Edit the config file, updating the worktree path so that it points to the new location of the submodule's working directory.
• Edit the .gitmodules file in the root of the master repository, updating the path to the working directory of the submodule.
• git add -u
• git add (It's important that you add the parent, and not the submodule directory itself.)

A few notes:

• The [submodule "submodule-name"] lines in .gitmodules and .git/config must match each other, but don't correspond to anything else.
• The submodule working directory and .git directory must correctly point to each other.
• The .gitmodules and .git/config files should be synchronised.