Git Submodules Cheat Sheet

ATTENTION: This page is out of date. It has not been updated since 2010, and probably will not be updated in the future.

(Pssst. Check out Your Git Submodule and You for more in-depth information.)

What you should know

• Submodules are a convenient way of putting a clone of another repository as a subdirectory within your main repository. The submodule is its own repository, and you can commit, branch, merge, etc. from inside it, just as with any other repository.
• A submodule’s contents aren’t stored in the main repository – the main repository stores only the URL and SHA1 hash referring to a commit in the submodule repository. It’s only on your local computer that the submodule files are in a subdirectory of your main repository.
• Unlike svn:externals, submodules point to a specific commit in the other repository, not a branch (whose code can change). Someone who clones your main repository next week will get the correct submodule code, even if the submodule has new commits upstream.
• That means if you want to point to a different (newer) submodule commit, you must make a commit in your main repository to update the reference.
• You cannot include only part of the other repository (e.g. one directory) as a submodule. You must include the entire other repository. Plan your repositories accordingly.

Recipes

Note: the [main]$ bits on each line represents your bash prompt. You should only type the stuff after the $.

• Set up the submodule for the first time:

  [~]$  cd ~/main/
  [main]$  git submodule add git://github.com/my/submodule.git ./subm
  [main]$  git submodule update --init
  [main]$  git commit ./submodule -m "Added submodule as ./subm"

• Fetch submodules after cloning a repository:

  [~]$  git clone git://github.com/my/main.git ~/main
  [~]$  cd ~/main/
  [main]$  git submodule update --init

• Pull upstream main repo changes and update submodule contents:

  [main]$  git pull origin/master
  [main]$  git submodule update

• Pull upstream changes to the submodule:

  [main]$  cd ./subm
  [subm]$  git pull origin/master   # or fetch then merge
  [subm]$  cd ..
  [main]$  git commit ./subm -m "Updated submodule reference"

• Edit and commit files in your submodule:

  [main]$  cd ./subm
  [subm]$  edit whatever.rb
  [subm]$  git commit whatever.rb -m "Updated whatever.rb"
  [subm]$  cd ..
  [main]$  git commit ./subm -m "Updated submodule reference"

• Push your submodule changes to the submodule upstream:

  [main]$  cd ./subm
  [subm]$  git push origin master