Field Notes

Git Submodules

November 08, 2014 | In 30 days / tech

git submodules came up three times this week. This is the first time I've run into them in all my time with git.

A submodule allows you to use one git repository within another. My current project can be described as a javascript game with a Python backend that's used by several other games. When I noticed an empty subdirectory with the name of the backend repo, I thought it was an orphaned symlink committed by accident.

Why might we use a submodule?

  • There's common code shared across multiple projects. A submodule is an alternative to keeping one giant repo with several unrelated projects for the sake of making updates available in a timely way.
  • The main module and submodule are deployed or run as one unit. The submodule is nested in the main module's file structure.

  • The main module and submodule must be run on the same host and port to prevent CORS issues. That is, some browsers puke if you request data behind the scenes from a different address because they perceive it as a security risk. This is especially true of older browsers like IE8. It will take a few more years for IE8 to cycle out of conservative IT sectors like hospitals and finance.

  • The submodule is only available through source code, and not distributed through other means. You don't have the dependency management tools you get with Ruby gems, npm modules, bower, etc.

Why wouldn't we use a submodule?

  • Familiarity. Many developer friends had heard of git submodules but never used them. Adopting a tool means everyone on the team needs to know how to use it, or that the use be automated.
  • Git updates require extra steps. With great power comes great overhead.

  • The complexity could grow quickly with more than one submodule.

  • Dependency management tools have evolved a lot in the past few years. We may have other ways to address the same need, and we're more accustomed to the smooth ride npm offers.

  • Deployment tools have also evolved. I suspect Puppet and Chef can handle pulling from multiple repos and deploying as one unit. I haven't dipped into these tools yet, so it's an educated hunch.

  • The trend of standalone applications talking to independent back end RESTful services has continued. An application might be designed differently so the submodule is a separate application. More recent browsers that support CORS may get their data from a different host and port.

  • Recommended reading:
    Git Submodules: Adding, Using, Removing, Updating for instant gratification
    Git submodules explained for a detailed explanation