Git submodules allow a repository to include a checkout of an external project as a subdirectory. Submodules maintain their own identity and commit information, so other developers cloning the main project can also easily clone the submodules. Partial checkouts are possible, allowing developers to choose which submodules to clone. When other developers clone a repository with submodules, they need to run additional commands to initialize and update the submodules.

1. git submodule
Olaf Alders
olaf@wundercounter.com
twitter.com/wundercounter
Toronto Perl Mongers
Sept 29, 2011

2. What does it do?
Git's submodule support allows a repository to contain, as a subdirectory, a checkout of an external project.
Submodules maintain their own identity; the submodule support just stores the submodule repository location and
commit ID, so other developers who clone the containing project ("superproject") can easily clone all the
submodules at the same revision. Partial checkouts of the superproject are possible: you can tell Git to clone none,
some or all of the submodules.
source: "Git Community Book"
http://book.git-scm.com/5_submodules.html

3. An Example:
mkdir shiny_app
cd shiny_app/
git init
mkdir inc
mkdir -p root/static/js
mkdir -p root/static/css
echo "shiny app" > README
git add .
git commit -a -m "initial commit"

4. Add a submodule
git submodule add https://github.com/twitter/bootstrap.git inc/bootstrap
git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# new file: .gitmodules
# new file: inc/bootstrap
cat .gitmodules
[submodule "inc/bootstrap"]
path = inc/bootstrap
url = https://github.com/twitter/bootstrap.git
git commit -a -m "adds bootstrap as submodule"

5. Link it up!
mkdir root/static/css
mkdir root/static/js
ln -s inc/bootstrap/bootstrap.min.css root/static/css/
ln -s inc/bootstrap/js root/static/js/bootstrap
git commit root -m "adds bootstrap symlinks"

6. Now what?
● Work as you normally would
● Later, when you want to update bootstrap to the latest version
cd inc/bootstrap
git pull origin master
cd ../..
git commit inc/bootstrap -m "updates bootstrap"

7. Cloning repos with submodules
When someone else clones your repo, they need to update and init:
$ cd ..
git clone shiny_app bootstrapper
Cloning into bootstrapper...
done.
$ cd bootstrapper/
$ ls
README inc root
olaf-alderss-macbook-pro:bootstrapper olaf
$ ls inc/bootstrap/
# no output above -- the inc/bootstrap folder is empty

8. Remember to init and update
We've got the repo, but the submodule is empty. Two commands will fix that.
$ git submodule init
Submodule 'inc/bootstrap' (https://github.com/twitter/bootstrap.git) registered
for path 'inc/bootstrap'
$ git submodule update
Cloning into inc/bootstrap...
remote: Counting objects: 3845, done.
remote: Compressing objects: 100% (1430/1430), done.
remote: Total 3845 (delta 2474), reused 3663 (delta 2329)
Receiving objects: 100% (3845/3845), 1.04 MiB | 388 KiB/s, done.
Resolving deltas: 100% (2474/2474), done.
Submodule path 'inc/bootstrap': checked out
'28c770bf679e131cc030c3bc4a1981450f831908'

9. Is your HEAD detached?
By default, the submodule in the cloned repo will not be on a
branch:
cd inc/bootstrap/
git branch
* (no branch)
master
Try to remember to work on a branch before committing:
$ git checkout master

10. Oops!
If you commit while not on a branch, you'll get the following "detached HEAD"
message:
$ git commit README.md -m "random change"
[detached HEAD b92b798] random change
1 files changed, 3 insertions(+), 0 deletions(-)
This is easy to recover from. Just check out a branch and merge the commit:
$ git checkout master
$ git merge b92b798

11. git pull != git submodule update
Team members should remember to change their workflow to:
git pull origin master
git submodule update
Remember, a pull does not fetch submodule updates. To stay
totally in sync, team members will want to update submodules
as they pull.

12. Caveat
Merge conflicts
If two team members commit the same submodule with
differing HEADs, you will get a merge conflict. You will need to
resolve this manually.

13. What do you gain from submodules?
● You can build and test against bleeding edge checkouts
● You don't have to add someone else's code to your repo
● Team members can build against exactly the checkout you've built and
tested against and vice versa
● Updating your submodules is trivial