Skip to content

Git Submodules

Git submodules are a way to nest repositories within other repositories.

Adding a Submodule

Use the git submodule add command to add a submodule to an existing repo.

cd myrepo
git submodule add [URL]
The [URL] is the location of the repository to be added as a submodule.

For example, adding a submodule via SSH destination: 

git submodule add git@github.com:username/repo-name.git
This does a couple of things:

  • Adds a directory for the submodule.

    • The submodule is named after the repo name, and by default is put in a self-named directory where you ran the command.

    • If you ran the git submodule add command in the root directory of your my-repo repository, the submodule will be in my-repo/repo-name.

  • Adds a .gitmodules file to the root of the repository.

    • This is an INI-style file: 
      [submodule "repo-name"]
    path = repo-name
    url = git@github.com:username/repo-name.git

The submodule will store a commit hash. This is the commit at which the submodule's files will be in sync with.

Cloning a Project with Submodules

When you clone a project that contains submodules, it will not populate those submodule directories by default.

git clone git@github.com:me/my-repo.git
If we look at the repo-name submodule that we added earlier, we can see if we have the files: 
ls -alh ./my-repo/repo-name
Empty!

However, you can use the --recurse-submodules option when cloning to populate the submodule.

git clone --recurse-submodules git@github.com:me/my-repo.git
This will populate any and all submodules nested inside the project.

If you've already cloned the repository but you forgot to use --recurse-submodules, you can use git submodule update with --init and --recursive to populate the submodules:

git submodule update --init --recursive

This is identical to running:

git submodule init
git submodule update
  • git submodule init: Initialize your local configuration file.
  • git submodule update: Fetch all the data from that project and check out the appropriate commit listed in the parent project.

Turning a Directory into a Submodule

If there is a subdirectory in a git repo that needs to be turned into a submodule (e.g., it needs to be its own repository and maintain its git history), it can be converted with git subtree split.

It is good practice to make a backup branch before performing this operation. 

cd /my-repo # Root of project repository
git branch backup-before-split

Then, extract the directory's git history.

git subtree split --prefix=my-repo/subdir --branch=new-repo-history

  • git subtree split: Creates a new history containing only a single directory.
  • --prefix=my-repo/subdir: Specifies the directory being extracted.
  • --branch=new-repo-history: Creates a local branch containing the rewritten git history.

This will make it so my-repo/subdir/src/main.py becomes src/main.py

Resources