How to use Git submodules in a project

· Category: Git

Short answer

Git submodules let you embed one Git repository inside another. Add one with git submodule add https://github.com/user/repo.git path/to/sub. Clone with git clone --recurse-submodules. For managing project dependencies more broadly, see how to install Python packages with pip.

Common commands

  • git submodule add <url> <path>: Add a submodule
  • git submodule update --init --recursive: Initialize and update after cloning
  • git submodule update --remote: Pull latest changes from upstream

Common pitfalls

  • Forgetting --recurse-submodules when cloning
  • Detached HEAD state in submodules after updates
  • Team members having different submodule commits

Tips

  • Pin submodules to specific commits rather than tracking branches for reproducibility
  • Consider Git subtrees or package managers as alternatives when submodules cause friction
  • See how to add a remote repository in Git for remote management