Renaming git submodules without moving them

Question

I have a submodule set up thus:

.gitmodules

[submodule "path/to/submodule"]
    path = path/to/submodule
    url = user@bitbucket.org:account/repo.git

Instead of having to reference it from the project root as 'path/to/submodule', I'd like to just be able to reference it as 'my_submodule'. e.g.

git submodule update --remote my_submodule

Everything I've read so far about this explains how to move the submodule, and that's not what I want to do. I have tried simply changing .gitmodules to

[submodule "my_submodule"]
    path = path/to/submodule
    url = user@bitbucket.org:account/repo.git

and .git > config to

[submodule "my_submodule"]
    url = user@bitbucket.org:account/repo.git
    active = true

but it just throws error: pathspec 'my_submodule' did not match any file(s) known to git

I hope someone out there can help. Thank you.

https://stackoverflow.com/search?q=%5Bgit-submodules%5D+rename — phd, Aug 27 '22 at 11:57
@phd thanks. I've already followed the exact process in your reply on that question (as detailed above), but there's nothing in your reply that helps me troubleshoot the error I got — Sarah, Aug 27 '22 at 12:12
Well, partially you're right. In addition to config changing you need to move `.git/modules/path/to/submodule` to `.git/modules/my_submodule` and edit the file `path/to/submodule/.git` pointing it to the new `.git/modules/my_submodule`. And partially wrong — you could never use `git submodule update my_submodule` because `git submodule update` takes **the path** to the submodule, not its logical name; see https://git-scm.com/docs/git-submodule . The only way to use `git submodule update my_submodule` is to **move** the submodule, not change its logical name. — phd, Aug 27 '22 at 14:49
AFAIU the sole purpose for submodules to have logical names is to distinguish them in `.gitmodules` and `.git/config`. And nothing else. People who give beautiful names or rename (change logical names) submodules do this for aesthetic, not practical purposes. — phd, Aug 27 '22 at 15:04
@phd thank you for the replies. to clarify, I didn't want to give my submodule a "beautiful" name for aesthetic purposes, I just wanted to interact with it without typing out the path every time I need to. I appreciate you reopening my question so that I get some helpful answers and discuss it with people who aren't making assumptions about my intentions or skill level, though. — Sarah, Aug 28 '22 at 20:18

score 3 · Accepted Answer · answered Aug 27 '22 at 22:48

As phd has noted in comments, a submodule's "logical name" is—at least currently¹—used only to locate values within in .gitmodules and the files in .git/modules/. You should leave the logical names alone here because they're private to Git itself. Or, to say this in fewer words: Don't do that!

¹There is a lot of work going on, over a long time period, in the background, as part of a project to make submodules not be the sob-modules that they still are. Things in the future may change. That's one reason not to mess with undocumented stuff about submodules now.

Extra information not relevant to the answer but that you should know

It's worth noting a historical oddity: submodules once were implemented by storing the .git directory / folder (whichever term you prefer) within the working tree of the submodule. That is, if you have:

repo/.git     # a top level repository
repo/foo/     # a folder within the superproject containing various files
repo/foo/sub  # a submodule of the superproject, in `foo/sub`

then repo/foo/sub/.git held the actual Git repository for the foo/sub submodule of this repository. Within repo/foo/sub/.git you would find the HEAD file, the refs/ directory, the objects/ directory, and so on.

This still works, but it has a rather obvious and nasty drawback. Suppose we're on the tip commit of branch develop, where we've added this new submodule. We now rewind to main, which does not yet have the submodule. Git needs to remove the foo/thing1, foo/thing2, etc., files, and because there's no submodule, Git wants to remove foo/sub as well.

If Git succeeds at removing foo/sub, the entire submodule repository—not just its checkout—is gone!

To fix this, Git long ago learned to "absorb" submodule Git directories into the superproject, storing them in .git/modules/ in the superproject. The .git in repo/foo/sub/ is now a file containing the path to the stored repository. If you have an old arrangement—which you can get by deliberately creating nested repositories before running git submodule add—you can run git submodule absorbgitdirs to move the submodule .git (repository proper) into the superproject's .git/modules directory. This makes it safe to check out a historical commit in which there is no such submodule: Git can safely remove the .git file without destroying the submodule repository, and later restore that .git file when moving to a commit that does use the submodule.

terrific answer, thank you so much for taking the time! Thankfully, all of the repos I work with on a daily basis employ the `.git/modules` arrangement and due to the directory structure of their filesystems they're all pretty snappy to work with. But there's always one, right? A pesky, submodule buried so far down that I get tendinitis every time I need to deal with it. At least now I have an appreciation of the logic and that takes the sting out a bit. Thank you! — Sarah, Aug 28 '22 at 20:29

Renaming git submodules without moving them

1 Answers1

Extra information not relevant to the answer but that you should know