Git Submodules Cheat Sheet

Last updated: 2010-01-26.

(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.


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:// ./subm
    [main]$  git submodule update --init
    [main]$  git commit ./submodule -m "Added submodule as ./subm"
  • Fetch submodules after cloning a repository:
    [~]$  git clone 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

6 thoughts on “Git Submodules Cheat Sheet”

  1. In the first recipe, shouldn’t the last line be:

    [main]$ git commit .gitmodules -m "Added submodule as ./subm"

  2. And if you want to update all the submodules of a project:

    $ git submodule foreach git pull origin master

    1. Doesn’t that command (foreach git pull origin master) update each submodule to master of the external submodules? That master is probably ahead of what works (or is tested) with your project.

      I think this command will update each submodule in project to latest version comitted in your project:
      $ git submodule update –init

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>