And here is where the problems starts. Let us assume that I want to make a change that is local to just this project.

Well, guess what, you can’t. Not if you intend to share this with other people. You need to push your changes to the submodules somewhere, and that means that if you need to fork the original project, update references to the project. Of course, if there is an update to the original submodule, you need to have two stages to update that.

And we haven’t spoken yet on the fun of pushing the main repository but forgetting to push the submodule. It gives a new meaning to “it works on my machine”.

In short, git submodules looks like a good idea, but they aren’t really workable in the real world. I’ll have a new post shortly showing how to deal with the issue

Comments

quote: " they aren’t really workable in the real world" - a bit harsh. With the adoption rate of git, I'd say that probably at least one team have found it workable in a real world.

As for your use-case, another quote - "Let us assume that I want to make a change that is local to just this project" - well then it is no longer really a shared resource, as it is manifested differently in every project using it, right?

if you keep it simple, put shared projects in a shared location, and localized stuff (like the disclaimer) within your main repo, then from "principle of least surprise" things are simple and straightforward. Have your build-script copy whatever needed to the artifacts/legal folder, and you're done.

I actually do not know how the download button works. I'd say that if you want to give people the ability to get the source without cloning (which makes them poor OSS citizens), then you'd host it somewhere and link from the Readme.

Now I never said that submodules are terrific or anything. They do work, for some people (most people do not submodule 25 projects anyway), just not as smoothly as we'd wish them to.

The whole point of having to pull them separately is when they aren't necessarily needed. I have an application that has two optional dependancies, I include them in the vendors folder and if someone wants to run my unit tests they can git submodule init vendor/something and then update it themselves. I'm not incurring extra burden in my pulls to make it easier for someone who's too lazy to type two commands.