The Native Solution: gitlinks and git submodule

Git contains a command designed to work with submodules, called git submodule. I saved it for last for two reasons:

  • It is much more complicated than simply importing the history of subprojects into your main project’s repository.

  • It is fundamentally the same as but more restrictive than the script-based solution just discussed.

Even though it sounds like Git submodules should be the natural option, you should consider carefully before using them.

Git’s submodule support is evolving fast. The first mention of submodules in Git development history was by Linus Torvalds in April 2007, and there have been numerous changes since then. That makes it something of a moving target, so you should check git help submodule in your version of Git to find out if anything has changed since this book was written.

Unfortunately, the git submodule command is not very transparent; you won’t be able to use it effectively unless you understand exactly how it works. It’s a combination of two separate features: so-called gitlinks and the actual git submodule command.


A gitlink is a link from a tree object to a commit object.

Recall from Chapter 4 that each commit object points to a tree object and that each tree object points to a set of blobs and trees, which correspond (respectively) to files and subdirectories. A commit’s tree object uniquely identifies the exact set of files, filenames, and permissions attached to that commit. Also recall ...

Get Version Control with Git now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.