Git submodules reference

submodules.md

An intro and cheatsheet for using git submodules.

Add submodule to project

$ git submodule add https://github.com/USERNAME/REPONAME PATH

e.g.

$ git submodule add https://github.com/hexojs/hexo-theme-landscape themes/landscape

The submodule will already be staged:

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        new file:   .gitmodules
        new file:   themes/landscape

So just commit.

Here are sample contents:

• .gitmodules config (in .ini format).

  [submodule "themes/landscape"]
      path = themes/landscape
      url = https://github.com/hexojs/hexo-theme-landscape

• themes/landscape - just a reference to a commit inside the submodule repo (in .diff format).

  diff --git a/themes/landscape b/themes/landscape
  new file mode 160000
  index 0000000..f20626c
  --- /dev/null
  +++ b/themes/landscape
  @@ -0,0 +1 @@
  +Subproject commit f20626cb882890bfc596b2fede01d8e80ea8f02e

Install submodules

To include submodule, clone the main repo with the --recursive flag.

$ git clone --recursive https://github.com/USERNAME/REPO_NAME

If you forgot to use the flag when you cloned, then just do this:

$ git submodule init
$ git submodule update

Update submodule

When you want to update a submodule to a newer version:

git submodule update

CLI

View help:

$ git submodule --help

See also git submodules in the git docs.