I Hate Git Submodules

Clickbait title. The author literally says &quot;Spoiler alert. I do not hate submodules.&quot; and also later recommends submodules for language ecosystems that don&#x27;t have built-in package managers.<p>The author also gives (IMO) 2 weak reasons against submodules.<p>(1) He says its hard to know which repo you&#x27;re editing (main repo or submodule). I agree, but in practice this hasn&#x27;t been an issue for me. A simple `git status` or `pwd` is usually enough to know which repo I&#x27;m editing.<p>(2) The author also says that committing changes with submodules can be confusing since it involves multiple commits: one commit in the submodule, and another in the main repo to update the commit it points to. I agree this is a little confusing at first and definitely tedious, but conceptually I think it is pretty simple.<p>That said, I do agree that submodules are confusing -- just for different reasons.<p>My main gripe with submodules are that they don&#x27;t work well with the rest of git. Why isn&#x27;t adding a submodule just a `git add` to a directory with a git repo inside of it? If there are new commits in a submodule, why doesn&#x27;t `git checkout .` reset it back to the commit the main repo points to? If I <i>clone</i> a repo with submodules, why do I need to run additional submodule commands to get an exact copy of the codebase? Basically, to me it feels like submodules were slapped onto git as an afterthought and little care was taken to think the git CLI experience as a whole. I think submodules would be a lot less confusing if git had designed a better CLI for it.

I&#x27;ve been the git fixer for a few different teams. I want to like submodules, but there&#x27;s something that doesn&#x27;t fit my brain the way the rest of git does. It feels half-baked. I think we&#x27;re still missing the best way to model the problem as a tree of related states.

This post is really hard to read. It mentions git submodules and then sharply veers into a bunch of seemingly barely-related paragraphs. If each section had one sentence at the top saying something about git submodules it would be a lot more coherent.

You spend all this time figuring out how to make git do what you want using this general format:<p><pre><code> git &lt;git-command&gt; [args] </code></pre> You would expect to do the same thing with a submodule, it would be:<p><pre><code> git submodule &lt;git-command&gt; [args] </code></pre> But no, submodules have their own set of commands. It&#x27;s like it&#x27;s purposefully obtuse for no good reason.

I routinely encounter problems where the file structure on disk gets out of sync with the .gitmodules file, or one of the internal files inside .git, and I need to completely recreate my local repo.<p>I dislike having to warn in the README file, &quot;somewhere in this repo are submodules, and you need to use this incantation to clone them.&quot;<p>I think you can now have the submodule reference point to a branch but it can&#x27;t point to a tag, which is what I want most of the time.<p>And there&#x27;s how `git status` just reports &quot;modified content&quot; without going into details.

What do people think of git subtrees?<p><a href="https:&#x2F;&#x2F;codewinsarguments.co&#x2F;2016&#x2F;05&#x2F;01&#x2F;git-submodules-vs-git-subtrees&#x2F;" rel="nofollow">https:&#x2F;&#x2F;codewinsarguments.co&#x2F;2016&#x2F;05&#x2F;01&#x2F;git-submodules-vs-gi...</a><p>Or the non-standard git-subrepo?<p><a href="https:&#x2F;&#x2F;github.com&#x2F;ingydotnet&#x2F;git-subrepo" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;ingydotnet&#x2F;git-subrepo</a>

I use them (occasionally), but only when the pain of not using them would be greater, because they are a blue-assed bitch.<p>But they really do enforce a very strict version control. If we want to be absolutely sure of a version, Git submodules will give that to you.<p>But I only use them in one PHP backend project that I plan to barely ever change, because every change means that I have to crawl through a raft of repos, updating a submodule chain.<p>It&#x27;s exactly the kind of operation that calls for a scripting solution, but it is also one of those projects, where I change it so seldom, that it isn&#x27;t worth it to write a script.<p>For my frontend (Swift) work, I use SPM (Swift Package Manager). Much easier on my nerves.

I&#x27;ve been maintaining a git repo at my current and previous employer - both started out with submodules, and got axed due to added complexity and cognitive load. After removal, they were not missed. Case closed.

I can only speak for myself. In the roughly 12 years I&#x27;ve been using git at multiple different companies and for my own projects, I have <i>never</i> used git submodules. I feel like I have a good, well rounded set of experiences too. Code bases big and small, massive monorepos, and many microrepos all separate. In none of them have we used submodules.<p>That being said, maybe submodules would have solved some problem here or there that we had. I&#x27;m open to arguments in favor of them in that case. But we&#x27;ve always been able to get the work done without them, so I don&#x27;t personally think they&#x27;re indispensable.

The biggest pain point for me has been that they&#x27;re basically incompatible with `git worktree`. By default they&#x27;ll just be cloned from upstream in the new worktree, thereby defeating the purpose of using worktrees in the first place.<p>I used to have a bunch of hacky scripts for working around this, but lately I&#x27;ve just been giving up and avoiding submodules as much as possible.

I was hoping to see better solutions to this problem in the comments, but the paucity of a solid solution means the problem isn&#x27;t solved yet. I agree with `qznc` below, in that once maturity is achieved, the monorepo should x-furcate and create packages, but up until that point there really is no clean solution for this relational concept.

It believe it is a question of maturity. If the subcomponent is mature enough, then turning it into a package is fine. The cost is that patching the subcomponent and testing the main component takes more effort (though you can script it). With submodules at least the build and test cycle is as quick as if it is in the same repo.<p>So there is a scale from quicker iteration to less coupled: same repo, submodule, different package. The question is in which cases the middle step &quot;submodule&quot; is worth it or if you should rather switch to one of the others always.

Everybody hates git submodules.

It might be worth looking at West, used by Zephyr (embedded RTOS): <a href="https:&#x2F;&#x2F;github.com&#x2F;zephyrproject-rtos&#x2F;west" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;zephyrproject-rtos&#x2F;west</a><p>Not sure how mature it is or if any other projects use it. But seems to be working well for Zephyr.

At least it is better than subtrees, which cannot tell you what they are even if you ask. Also, ClearCase isn&#x27;t atomic beyond file level even... you use labels to make &quot;versions&quot;.

About the point of it not being obvious where you&#x27;re working: I find using zsh or another shell that prints git information as part of the shell prompt helps immensely with this.

I don&#x27;t see the point of submodules. If you want to make a change in another repo, do that. If you want to reference a specific version of another package in your code, do that. When would I want submodules?

They are a pain but they come in handy for us.<p>The main thing I learned is if you mess up any part of your submodule during creation - do not try to fix it. Just delete it from the parent repo and start over.<p>Also do not bother deleting it using git commands. Delete it in the .gitmodules file, then search your .git folder for every reference of the repo you want to delete (including folders named after it) and delete everything.<p>Either that or start with a clean parent repo clone.

i wish git would implement a built in subsplit feature

They are a nightmare

git subtree<p>They came about because everyone hates submodules.

then don&#x27;t use them?

Me too, and that&#x27;s why i work whenever possible with BitKeeper and nested repositories.

Also hate them. Far better to have a dependency pulling shell script - no overhead of git yak shaving - just maintaining the URIs.

If you get to a point where you think you <i>absoultely</i> need git submodules...just switch to svn, so much pain in misery can be avoided if you just use the right tool for the right job and SVN handles the git submodule use-case effortlessly (for C++ at least).<p>For languages with proper package management (ruby, python, go, node, etc...) put in the extra effort to utilize your package manager to update your dependencies instead of bothering with submodules. If you&#x27;re still set on doing submodules, I&#x27;m willing to be you&#x27;re just &quot;doing it wrong&quot; (TM).

I also hate monorepos. I consider the monorepo to be an anti-pattern.<p>It&#x27;s an architectural advantage to separate each module into a different repo as it encourages careful separation of concerns.<p>If you find that you often need to update many modules together every time you want to add a new feature to your project, this is often an indication that your modules do not have proper separation of concerns and your abstractions are leaking. It means your project exhibits low cohesion and&#x2F;or tight coupling between modules.<p>The difficulty in maintaining separate module dependencies is actually a very useful signal to you as a developer that your code is too tightly coupled and needs to be refactored into modules which are more independent.<p>Monorepos are a bandaid patch solution which covers up the root problem. The real problem is incorrect separation of concerns, AKA low cohesion which leads to tight coupling between your components.<p>It&#x27;s not possible to design simple interfaces between components when these components have overlapping responsibilities.