Git Submodule Cheatsheet

I’m aware git submodules aren’t awesome, but a lot of what makes them a pain is having to remember the arcane sequence of commands to invoke when using them in a collaborative team project. I’m creating this cheat sheet for my own reference. If you find it useful too, or have suggestions for improving it (or if you spot errors to correct), let me know.

Adding a submodule to a project

$ cd <repo root>
$ git submodule add <readable remote submodule repo> <relative local path to install target>

Making changes to a submodule

Here we want to first push our changes to the submodule’s upstream repo, and then record the change in the parent project repo. It’s very important to not skip the first part, as that would break the submodule for other developers when they pull changes to the parent project with an updated reference to a nonexistent state of the submodule repo.

$ cd <submodule path>
// do stuff
$ git commit ... // Changes committed to submodule; parent repo only recognizes that submodule's commit has changed
$ git push ... // Push submodule changes; parent repo unaffected
$ cd <anywhere within parent repo>
$ git commit ... // Commit updated reference to new submodule state (reference by commit)
$ git push ...
// Tell your fellow coders to be sure and update submodules when they next pull.

Cloning a repo with submodules for the first time

After cloning the repo, initialize and update your submodules. git submodule init sets up the repo structure. git submodule update populates submodule files by pulling their commits.

$ git clone ...
$ git submodule init
$ git submodule update

Pulling commits including updates to submodules

$ git pull ...
$ git submodule update

Add your thoughts