How gitsubmodules (actually) work

Gitsubmodules is probably one of the most confusing features git has to offer. Forget about the infamous rebases, I’m not even sure about how Gitsubmodules should be called.

Top 2 search results for the keyword “gitsubmodules”

So, is it “Git submodules” or “Gitsubmodules”?

But here are some quick answers that might help you get started with this feature.

The basics

When you first cloned a repository with submodules, you should do git submodule update --init, or if you want to also set up the submodules within the submodules, add a --recursive option to it.

You cannot directly edit the .gitsubmodules file, it doesn’t work!

Yes, adding a new section there won’t work. You will need to use the git submodule add command to add a new submodule.

What is actually adding the submodule is the commit that is automatically staged after you executed the command. Remember to commit them as if you unstage them it will be gone forever.

Submodules point to a specific commit, not to track a branch

If you are curious and cd into the directory where a submodule resides, and execute git status, you’ll realize the status reads something like “detached HEAD”. This is because submodules are set to track a specific commit, and not the latest commit of a branch.

To get the latest commit (which most of you probably want), you need to execute:

git submodule update --remote

And consequently you’ll see a new change appears in your unstaged files, which contains information about the new commit this submodule is pointing to. If you commit this change, when other people clone your repository and pull the submodules, they will get the exact commit you just checked out.

Leave a Comment