git submodule

With the git submodule command, you can include one Git repository inside another as a subdirectory. This is most useful when you want to reuse shared code — such as a library or framework — across multiple projects without copying it.

Adding a submodule

To add a submodule, run the following from the root of your repository:

$ git submodule add https://github.com/myotherproject/myotherrepository subfolder
Cloning into 'subfolder'...
remote: Counting objects: 11, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 11 (delta 0), reused 11 (delta 0)
Unpacking objects: 100% (11/11), done.
Checking connectivity... done.

By default, Git creates a folder named after the remote repository. You can override this by specifying a different folder name after the URL, as shown above.

This will create (or update) a .gitmodules file that records the submodule's local path and remote URL. Once you've added the submodule, commit and push the change:

$ git commit -am "Added myotherrepository submodule"
[main 1234abc] Added myotherrepository submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 subfolder
$ git push origin main

Cloning a repository with submodules

When you clone a repository that contains submodules, the submodule directories will be empty by default. To clone everything in one step, use the --recurse-submodules flag:

$ git clone --recurse-submodules https://github.com/myproject/myrepository

This clones the main repository and then automatically initialises and fetches all of its submodules.

Initialising submodules after cloning

If you've already cloned a repository without --recurse-submodules, you can set up the submodules afterwards with two commands:

$ git submodule init
$ git submodule update

git submodule init registers the submodule paths from .gitmodules into your local Git config. git submodule update then fetches the correct commit for each submodule and checks it out.

Updating a submodule

If the remote repository for a submodule has been updated and you want to pull the latest changes into your project:

$ git submodule update --remote --merge

This fetches the latest commit from each submodule's remote and merges it. You'll then need to commit and push the change so other collaborators pick it up.

Removing a submodule

Removing a submodule takes a few steps. First, unregister the submodule and remove its files:

$ git submodule deinit -f subfolder
$ git rm -f subfolder

Then clean up the leftover Git internal data:

$ rm -rf .git/modules/subfolder

Finally, commit the removal:

$ git commit -m "Removed subfolder submodule"

This fully removes the submodule entry from .gitmodules, your .git/config, and the working directory.

If you run into issues with submodule paths during deployment, see our FAQ on adding files at a submodule path.

DeployHQ supports deploying repositories that use submodules — it can automatically fetch and deploy submodule contents alongside your main project.