A submodule is a repository dependency. This means that while it’s needed for a given repository, it isn’t part of that repository, having instead a separate repository of its very own.

This subtle nuance can present itself in the form of a particularly opaque problem when cloning a project with submodules.

Let’s say you’re cloning a project like Mantis Bug Tracker. MantisBT relies on several submodules, including PHPMailer. Maybe you know this, probably you don’t. You clone it to the server, then point a browser at the directory, figuring there’ll be some sort of installation form you need to complete in order to get Mantis up and running (which there is).

However, instead of presenting you with a form, your browser barfs out an error:

External library '/mantis/library/phpmailer/PHPMailerAutoload.php' not found.

Checking this directory reveals, sure enough, the above-named file is MIA. What to do? Did the clone function not download the complete repository?

Well, sort of.

It cloned the entirety of the Mantis repository but none of the submodules — which it shouldn’t have, because you only told it to clone the Mantis repository, which it did.

You can see how this could be characterized as opaque.

What needs to happen now is to clone the submodules. This is done with two commands:

git submodule init

This initializes your local configuration file. Then:

git submodule update

This is equivalent to running git clone on all of the project dependencies. You reload the browser window and voilà — there’s your install form.

This is far from the worst problem submodules can present but unless you’re setting up the project yourself, sometimes it’s not a choice to use them or not.