Rename a git submodule

Is there some easy way to rename a git submodule directory (other than going through the entire motion of deleting it and re-adding it with a new destination name).

And while we are at it, why is it that I simply cannot do the following in the parent directory: git mv old-submodule-name new-submodule-name


Git1.8.5 (October 2013) should simplify the process. Simply do a:

git mv A B

"git mv A B", when moving a submodule A has been taught to relocate its working tree and to adjust the paths in the .gitmodules file.


See more in commit 0656781fadca1:

Currently using "git mv" on a submodule moves the submodule's work tree in that of the superproject. But the submodule's path setting in .gitmodules is left untouched, which is now inconsistent with the work tree and makes git commands that rely on the proper path -> name mapping (like status and diff) behave strangely.

Let "git mv" help here by not only moving the submodule's work tree but also updating the "submodule.<submodule name>.path" setting from the .gitmodules file and stage both.
This doesn't happen when no .gitmodules file is found and only issues a warning when it doesn't have a section for this submodule. This is because the user might just use plain gitlinks without the .gitmodules file or has already updated the path setting by hand before issuing the "git mv" command (in which case the warning reminds him that mv would have done that for him).
Only when .gitmodules is found and contains merge conflicts the mv command will fail and tell the user to resolve the conflict before trying again.


git 2.9 (June 2016) will improve git mv for submodule:

See commit a127331 (19 Apr 2016) by Stefan Beller (stefanbeller).
(Merged by Junio C Hamano -- gitster -- in commit 9cb50a3, 29 Apr 2016)

mv: allow moving nested submodules

"git mv old new" did not adjust the path for a submodule that lives as a subdirectory inside old/ directory correctly.

submodules however need to update their link to the git directory as well as updates to the .gitmodules file.


I found following workflow working:

  • Update .gitmodules
  • mv oldpath newpath
  • git rm oldpath
  • git add newpath
  • git submodule sync

Note: this approach does not update the index and .gitmodules properly in 2018 versions of GIT.

Note: You may be able to now just do git mv oldpath newpath now, as pointed out in VonC's answer. (Ensure you are using the latest version of git)


The correct solution is:

mv oldpath ~/another-location
git rm oldpath
git submodule add submodule-repository-URL newpath

Source: Rename git submodule


I just tried a few of the suggested above. I'm running:

$ git --version
git version 1.8.4

I found it was best to de-init the submodule, remove the directory and create a new submodule.

git submodule deinit <submodule name>

git rm <submodule folder name>

git submodule add <address to remote git repo> <new folder name>

At least that is what worked for me best. YMMV!