Git submodules

I think I’m ready to discuss Git submodules. My chronic problem with submodules is that I don’t use them often enough to understand how they work. From what I gather, you can do a lot more than what I’ll cover, but I’m only interested in just placing a repo in a repo.

The benefit of submodules is that you can reduce duplicate code. Instead of copying files from one repo into another, Git can manage this for you. v3 currently has 6 submodules. These are helpful for pulling changes to external repos — in our case jquery-smartresize and jquery.form.js.

I’ve been breaking out re-useable bits of code into smaller repos and gists. So I’ve got this requestAnimationFrame polyfill, and I want to include it in another project, Inflickity. This can be done with two git submodule commands:

git submodule add git:// request-animation-frame
git submodule update --init

This will add the submodule, then pull in the appropriate commit. I’ll be able to use request-animation-frame/requestanimationframe.js in the Inflickity demo.

Both those commands trigger a change in the repo, changing .gitmodules and reference to the submodule repository. This change will require a commit.

If anyone else clones the repo, they’ll have to update and init the submodules as well.

git clone
cd inflickity
git submodule update --init

EDIT Or better yet, clone the repo and pull in submodules with git clone --recursive (thx Mathias):

git clone --recursive

Now, the crazy-pants part. Per the Git reference, git submodule update

will make the submodules HEAD be detached

I think this is where I usually lose control of what was happening with my submodules. The submodule’s repository has checked out the specific commit, and is not on the master branch as I would have expected. For example, let’s try cloning the Inflickity repo and getting that submodule working.

~/projects $ git clone
Cloning into inflickity...
Unpacking objects: 100% (87/87), done.
~/projects $ cd inflickity
~/projects/inflickity $ git submodule update --init
Submodule 'request-animation-frame' (git:// registered for path 'request-animation-frame'
Cloning into request-animation-frame...
Submodule path 'request-animation-frame': checked out 'db50266cd98d2d46277fd54d24cfd37766476a00'
~/projects/inflickity $ ls request-animation-frame/

Great, so the contents of the submodule are there. But what happens if we check the status of that submodule repository:

~/projects/inflickity $ cd request-animation-frame/
~/projects/inflickity/request-animation-frame $ git status
# Not currently on any branch.
nothing to commit (working directory clean)

Not on any branch. Darnit. This will prevent the basic git pull from working, so you’ll have to specify remote and branch.

~/projects/inflickity/request-animation-frame $ git pull origin master
From git://
 * branch            master     -> FETCH_HEAD
Already up-to-date.

git submodule foreach allows you to run a shell command for each submodule, which is ideal for pulling all submodules.

~/projects/inflickity $ git submodule foreach 'git pull origin master'
Entering 'request-animation-frame'
From git://
 * branch            master     -> FETCH_HEAD
Already up-to-date.

Just like when adding submodules, if there are any new commits that were pulled for a submodule, you’ll need to track that change in a commit for the parent repository.

In review, my three go-to git submodule commands are:

# starts it off
git submodule update --init
# for anyone else cloning
git clone --recursive my-repo.git
# pull in any fresh commits
git submodule foreach 'git pull origin master'

This keeps me in the parent repo, and I don’t get confused popping in and out of submodules repo.