230

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

5
  • 9
    You will no longer need to update .gitmodules manually when moving a submodule. see my answer below
    – VonC
    Sep 10, 2013 at 7:17
  • Git modules are too complicated. npm shows how simple works. One day... maybe... someone... will rewrite it... in the meantime...
    – Rolf
    Mar 18, 2018 at 15:00
  • 2
    @VonC's answer is not the full story as of today: it will indeed change .gitmodules, but will just rename the path, not the module name. You need an additional edit to .gitmodules to correct that and a 'git submodule sync' to complete the full process
    – zertyz
    Dec 7, 2018 at 22:06
  • @zertyz: The property [submodule "name_of_submodule"] is a Git internal name, you can rename it for not confusing yourself but it's just a label.
    – MKesper
    May 16, 2019 at 7:59
  • The title is misleadiing. It should be "Change a git submodule path" Renaming of a submodule is not possilbe AFAIK. ie the "path" and "url" parts of .gitmodules can be manipulated but not submoudle declaration. If you want the module name to be aligned with the path, you have to delete and reCreate. Apr 6, 2020 at 12:31

7 Answers 7

326

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.

26
  • @checksum But 1.8.5 has a stable release, for at least some... hours ;) github.com/git/git/releases/tag/v1.8.5
    – VonC
    Nov 29, 2013 at 6:16
  • 2
    @MaksimDmitriev but what about a ppa (Personal Package Archive) that I mentioned in stackoverflow.com/a/20918469/6309?
    – VonC
    Jan 17, 2014 at 20:32
  • 2
    git mv just does not work for this purpose on my machine. Jan 30, 2019 at 7:22
  • 1
    @VonC Using "git mv currentname newname" - I get the error "fatal: cannot move directory over file source=currentname , destination=newname/currentname"... git version 2.23.0.windows.1 in windows 10, running from git bash. The currentname and newname only differ by the case of the first letter (e.g. Code -> code). Jul 26, 2020 at 13:01
  • 1
    @VonC I've solved it by renaming it to a temp name and then to the correct name - I suspect it was due to the fact that the names differ only in their case, and windows' paths are case insensitive. Although the error message could have been more helpful. Jul 27, 2020 at 5:54
121

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 just do git mv oldpath newpath now, as pointed out in VonC's answer. (Ensure you are using the latest version of git)

12
  • 23
    note to self: for git add newpath don't use a trailing slash
    – atomicules
    Jul 28, 2011 at 15:17
  • 10
    With such a workflow, you will only create a symlink to the sub-directory you use as a submodule. Symlink is just a part of the global submodule functionality. This mean that when you clone the repo that use the renamed submodules, you may end with the following error: No submodule mapping found in .gitmodules for path 'your-oldpath' After you remove the oldpath (*git rm oldpath), you should use git submodule add REPO-URL newpath instead of "git add newpath*. When done, git status will display something like this: renamed: oldpath -> newpath
    – Bertrand
    Jan 26, 2012 at 9:45
  • 5
    This solutions doesn’t work for me because when using git add command, the submodule was included into the project as a simple directory and not as a submodule. try $ mv submodule-oldpath ~/another-location $ git rm submodule-oldpath $ git submodule add submodule-repository-URL submodule-newpath bcachet.github.io/development/2012/05/25/rename-git-submodule May 6, 2013 at 15:07
  • 3
    If you do have the problem with the working tree, you can also edit the .git/modules/SUBMODULE/config file, such that the worktree points to the the right directory again. Apr 10, 2014 at 14:24
  • 5
    This did not worked for me with git 2.13.1. But simply doing git mv old new works like a charm. I only need to do git commit to complete the changes. Jul 20, 2017 at 23:17
19

The correct solution is:

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

It's not possible to rename it, so you've to remove it first (deinit) and add it again.

So after removing it:

git submodule deinit <path>
git rm --cached <path>

you may also double check and remove the references to it in:

  • .gitmodules
  • .git/config
  • remove reference folder from .git/modules/<name> (best to make a backup), as each folder has config file where it keeps the reference to its worktree

then stage your changes by committing any changes to your repo by:

git commit -am 'Removing submodule.'

and double check if you don't have any outstanding issues by:

git submodule update
git submodule sync
git submodule status

so now you can add the git submodule again:

git submodule add --name <custom_name> [email protected]:foo/bar.git <my/path>
2
  • also it is actually today
    – Alexey
    Oct 12, 2018 at 12:53
  • 3
    The questions title is a misnomer, it pertains to the path, not name Apr 6, 2020 at 12:33
12

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!

5

MacOs: When I wanna use VonC solution to change submodule folder Common to lowercase:

git mv Common common

I get

fatal: renaming 'Common' failed: Invalid argument

Solution - use some temporary folder name and move twice:

git mv Common commontemp
git mv commontemp common

That's all :)

4

Edit the .gitmodules file to rename the submodule and then rename the submodule directory.

I think you might need to do a git submodule sync afterwards, but I'm not in a position to check right now.

2
  • This causes the new submodule name to occur as a new commit and not as a rename. But perhaps this is the way it has to be ? Dec 24, 2010 at 15:04
  • 1
    @Lars: Do be sure to remove the old submodule directory too!
    – Cascabel
    Apr 4, 2011 at 14:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.