How to configure and use Git submodules for dependency management?

Submodules in Git are a mechanism that allows you to embed one independent repository inside another repository as a subdirectory. This is especially useful when your project depends on a third-party library or a shared module that is developed separately, but you want to be able to lock the exact working version of this dependency right in your code.

To add a new submodule to a project, use the git submodule add command, followed by the remote repository URL of the library and the path where it should be located in your project. After running this command, Git clones the specified repository inside your project and creates a special configuration file .gitmodules, which stores metadata about the connected dependencies.

It is important to understand that when cloning a main repository that contains submodules, the submodule folders remain empty by default. To download their contents after cloning, a developer needs to initialize and update the submodules using the git submodule update --init --recursive command. The recursive flag ensures that even nested submodules are downloaded, if any exist.

Working with code inside a submodule has its own specifics. When you enter the submodule folder, you enter the state of a separate independent repository with its own HEAD pointer. If you made changes to the submodule code and committed them there, the main project will not pick up these changes automatically. The parent repository will simply update the commit hash that the submodule points to, and this new hash will need to be recorded with a separate commit.

To update all submodules in a project to the latest versions from remote repositories, use the git submodule update --remote command. This allows you to quickly pull the latest changes from external dependencies. Removing a submodule requires manually deleting the entry from the .gitmodules configuration file, clearing the Git cache, and deleting the dependency folder itself from the disk.