Git: why submodules are evil

Submodules look cool but in reality they’re hot as hell.

This article briefly shows why people want to use submodules and in the section after why they shouldn’t use them.


When git users come across submodules the first time they look attractive and nice because they seem to be one way to better structure a project where some parts could be put in their own repositories.

Essentially most people’s intention is to extract some parts in a way that other people can get a copy of this little part without the need to become familiar with the whole project structure.


Submodules would put a smile on people’s faces if there weren’t some issues.

#1: Submodule Update

By executing git submodule update changes in a submodule are silently overwritten instead of merging them.

#2: See changes made in the whole project …

… or not.

In the parent (root) repository git status shows changes in this parent repository but it does not include changes of submodules. Instead it says something has changed in this submodule.

If submodules have a strong relationship to each other it’s hard to track changes across multiple submodules.

#3: Your history will be broken

In the following the commits 89c99bc and 3e0b43e are updates of submodule references.

89c99bc Documentation update
b9bd1d1 New helper to make columns from an array.
0cce430 New: helper functions
3e0b43e Directory code improved

A reference update means that you (could) have made a lot of changes in submodules but in the parent git repository these changes show up in one single message, essentially describing that you updated the reference.

The repo history simply breaks and this is just another thing that makes your life harder. Just imagine that bugfixing also includes commit messages to be read.

#4: Using Git in the shell only

In a shell only there’s more work with a repository using submodules than with a repository with no submodules.

Scenario: files in different submodules must be changed and the main repository updated to keep these changes together when pulling from the main repository on another client.

Steps to be done:

cd submodule1
git add file1 file2
git commit -m "some changes in submodule1"
git push
cd ../submodule2
git add file3 file4
git commit -m "some changes in submodule2"
git push
cd ..
git add submodule1 submodule2
git commit -m "Updated submodule1 and submodule2"
git push

Steps to be done if no submodules are involved:

git add submodule1/file1 submodule1/file2 submodule2/file3 submodule2/file4
git commit -m "I made this and that"
git push

The extra work comes from: first commit all the changes in your submodules!


Avoid submodules if you don’t need them. They don’t simplify your life – on the contrary you’ll have more work and trouble in certain situations.

Other people are experiencing the same or quite similar:

You also need to teach new project team members:


  1. rohieb

    Okay, that’s not how I use submodules at all. I rather use them to include external projects, which have nothing to do with my project, and I’m only interested that they exist somewhere in my repo (like a black box). For example, if I’m using a library libfoo in my application, I include it as a submodule, so people get it easier when they clone my code. I’m not interested in the whole history of libfoo, I’m only interested that it’s there, especially if my Makefiles etc. expect it to be in a specific place and if I need libfoo at a specific version.

    For the scenario you described, with content that “belongs together” in a certain way, I also would not use submodules. I guess many people think of submodules as a cheap way to emulate Subversions behaviour so they can check out small portions of the repo without needing to get the repo as a whole, but this is clearly not how the Git philosophy sees a repo (remember, Git tracks content, not files). Instead, I usually break up my projects into small parts that can exist as solitary projects and have a clearly defined interface on the outside so they can be reused (and exchanged) easily. And in this case, submodules do make sense, since I get a more abstracted view on my repo.

  2. To start off, you want to have the name of the track.
    After the first week, they trade with one of the friends from the group
    and continue until everyone has a chance to try all
    of them. Sometimes a person likes to take a bath although talking to their friends or listening to
    a symphony and this is tough without the proper accessories.

  3. Very good blog! Do you have any suggestions for aspiring writers?

    I’m planning to start my own website soon but
    I’m a little lost on everything. Would you advise starting with a free platform like WordPress or go for a paid option? There are so many options
    out there that I’m completely overwhelmed .. Any ideas? Thanks a

Trackbacks / Pings

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>