Git Submodule Basic Usage Examples

Last updated:

Create submodule

This creates a submodule, but files aren't actually downloaded

Inside an existing git repository, do:

$ git submodule add git://github.com/some_user/some_project.git path_to_some_project

Initialize (populate) submodule

(This is where files get actually downloaded)

In the outer repository, do:

$ git submodule init

and then do:

if the submodule refers to a remote repo, do git submodule update --remote instead

$ git submodule update

Update submodule

$ git submodule update

Remove submodule

  1. $ git rm --cached <submodule_name>

  2. Delete the relevant lines from file .gitmodules

  3. Delete the relevant section from file .git/config or run git submodule deinit <submodule_name> if on newer git versions

  4. Commit the changes

  5. Delete the now untracked submodule files

  6. Remove directory .git/modules/<submodule_name>

Reset all submodules in repository

  1. $ git submodule foreach --recursive git clean -xfd

  2. $ git reset --hard

  3. $ git submodule foreach --recursive git reset --hard

  4. git submodule update --init --recursive

Clone repository with submodules

  1. $ git clone --recursive git@github.com:name/repo.git

Update repo and submodules together

  1. $ git pull origin master

  2. $ git submodule sync --recursive

  3. $ git submodule update --init --recursive

Display submodule information in git status

Update git configuration as follows:

$ git config --global status.submoduleSummary true

Dialogue & Discussion