Mastering Git submodules

I use them daily and they're painful! Thankfully, there's Peru [0]. Unfortunately, it only works on Python 3.3+.

[0] https://github.com/buildinspace/peru

Interesting overview!

Some of this caveats are kinda surprising for me, coming from a Mercurial background:

* Every time you add a submodule, change its remote’s URL, or change the referenced commit for it, you demand a manual update by every collaborator. Forgetting this explicit update can result in silent regressions of the submodule’s referenced commit. -- This is something handled automatically in Mercurial. Is there any reason why the same behaviour is not used in Git?

* Commands such as status and diff display precious little info about submodules by default. -- This should be possible to implement, no? It's also something that's available in Mercurial (using the --subrepos flag), and it's a huge boost to usability.

I wrote very a brief how-to on Git Submodules [1] for my colleagues a while ago, because a lot of people seemed to have trouble with it. It explains the real basics and how to use them painlessly in most situations. So it's much shorter than the OP's article and that might help if you don't want to force everyone in your team to read a big article like this.

[1]: https://gist.github.com/gitaarik/8735255

I use git-subrepo too, but it has its own sets of warts. It generates pretty verbose (and ugly) commit messages made of json. It doesn't let you do anything (like a pull or clone) when you working directory is dirty.

But on the whole, it is often less painful than submodules. I haven't tried subtree yet, will do that next :-)

At work we have a git repository called the 'projectname/super-project'. Developers clone this repo, and all it contains is a pair of shell scripts and a bunch of git modules. A module for every project, it's a SaaS cluster, we have projects like 'http-frontend', 'http-backend', 'gateway', 'indexer', 'marketing-website' and some forks of open source projects we customized for our use case.

After a fresh developer has cloned the super project, they just run the `./setup` shell script and it will inform them of any dependencies their system doesn't meet and then start the docker provisioning process. All subprojects have docker containers associated with them, and we have shell scripts that launch all docker containers and link them together.

A new developer can cold provision the entire cluster on their laptop in a matter of minutes, pretty neat :)