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 most modern answer, taken from Valloric's comment above:

1. Upgrade to Git 1.9.3 (or 2.18 if the submodule contains nested submodules)
2. git mv old/submod new/submod
3. Afterwards the .gitmodules and the submodule directory are already staged for a commit (you can verify this with git status.)
4. Commit the changes with git commitand you're good to go!

Done!

Answer 2

[Update: 2014-11-26] As Yar summarizes nicely below, before you do anything, make sure you know the URL of the submodule. If unknown, open .git/.gitmodules and examine the keysubmodule.<name>.url.

What worked for me was to remove the old submodule using git submodule deinit <submodule> followed by git rm <submodule-folder>. Then add the submodule again with the new folder name and commit. Checking git status before committing shows the old submodule renamed to the new name and .gitmodule modified.

$ git submodule deinit foo
$ git rm foo
$ git submodule add https://bar.com/foo.git new-foo
$ git status
renamed:    foo -> new-foo
modified:   .gitmodules
$ git commit -am "rename foo submodule to new-foo"

Answer 3

The string in quotes after "[submodule" doesn't matter. You can change it to "foobar" if you want. It's used to find the matching entry in ".git/config".

Therefore, if you make the change before you run "git submodule init", it'll work fine. If you make the change (or pick up the change through a merge), you'll need to either manually edit .git/config or run "git submodule init" again. If you do the latter, you'll be left with a harmless "stranded" entry with the old name in .git/config.

Answer 4

I just went through this ordeal yesterday and this answer worked perfectly. Here are my steps, for clarity:

1. Ensure that submodule is checked in and pushed to its server. You also need to know what branch its on.
2. You need the URL of your submodule! Use more .gitmodules because once you delete the submodule it's not going to be around
3. Now you can use deinit, rm and then submodule add

EXAMPLE

• Git submodule is in: Classes/lib/mustIReally
• Moving to: lib/AudioBus
• URL: http://developer.audiob.us/download/SDK.git

COMMANDS

    git submodule deinit Classes/lib/mustIReally
    git rm foo
    git submodule add http://developer.audiob.us/download/SDK.git lib/AudioBus

    # do your normal commit and push
    git commit -a 

NOTE: git mv doesn't do this. At all.

Answer 5

Note: As mentioned in the comments this answer refers to the steps needed with older versions of git. Git now has native support for moving submodules:

Since git 1.8.5, git mv old/submod new/submod works as expected and does all the plumbing for you. You might want to use git 1.9.3 or newer, because it includes fixes for submodule moving.

---

The process is similar to how you'd remove a submodule (see How do I remove a submodule?):

1. Edit .gitmodules and change the path of the submodule appropriately, and put it in the index with git add .gitmodules.
2. If needed, create the parent directory of the new location of the submodule (mkdir -p new/parent).
3. Move all content from the old to the new directory (mv -vi old/parent/submodule new/parent/submodule).
4. Make sure Git tracks this directory (git add new/parent).
5. Remove the old directory with git rm --cached old/parent/submodule.
6. Move the directory .git/modules/old/parent/submodule with all its content to .git/modules/new/parent/submodule.
7. Edit the .git/modules/new/parent/config file, make sure that worktree item points to the new locations, so in this example it should be worktree = ../../../../../new/parent/module. Typically there should be two more .. than directories in the direct path in that place.

8. Edit the file new/parent/module/.git, make sure that the path in it points to the correct new location inside the main project .git folder, so in this example gitdir: ../../../.git/modules/new/parent/submodule.

   git status output looks like this for me afterwards:

   # On branch master
   # Changes to be committed:
   #   (use "git reset HEAD <file>..." to unstage)
   #
   #       modified:   .gitmodules
   #       renamed:    old/parent/submodule -> new/parent/submodule
   #
   

9. Finally, commit the changes.

Answer 6

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 <parent-of-new-submodule-directory> (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.