git-submodule

Install a repository's specified submodules

$ git submodule update --init --recursive

$ git submodule add [repository_url]

$ git submodule add [repository_url] [path/to/directory]

$ git submodule foreach git pull

git submodule add repository [path]
git submodule status [path]
git submodule init [path]
git submodule update [path]
git submodule deinit [-f|--force] (path)...
git submodule set-branch [-b branch] [--default] submodule
git submodule summary [--cached|--files] [commit] [path]
git submodule foreach [--recursive] command
git submodule sync [--recursive] [path]
git submodule absorbgitdirs

add repository [path]
    Add the given repository as a submodule to the specified path. If no path is specified, the name of the repository is used as the path.

status [path]
    Show the status of the submodules. Displays commit ID and any modifications.

init [path]
    Initialize the submodule configuration by registering each submodule name from the .gitmodules file.

update [path]
    Update the content of the submodules by checking out the commit recorded in the superproject.

deinit [-f|--force] (path)...
    Unregister the given submodule from the working tree. Requires that the submodule have no local modifications.

set-branch [-b branch] [--default] submodule
    Sets the branch for the specified submodule in .gitmodules.

summary [--cached|--files] [commit] [path]
    Show a summary of changes in submodules.

foreach [--recursive] command
    Execute the given command in each submodule.

sync [--recursive] [path]
    Synchronizes the remote URL configuration setting in each submodule with the value specified in the superproject.

absorbgitdirs
    Moves .git directories inside submodules to the standard location.

The git submodule command suite allows you to manage Git repositories embedded as subdirectories within another Git repository. Submodules provide a mechanism to include and track specific commits from other projects without directly copying the code. They essentially record the commit ID of an external repository within your main project. This allows you to update your project to a specific version of the submodule. Common operations include adding, updating, initializing, and removing submodules. Submodules maintain a link to the external repository, enabling collaborators to clone the main project and then retrieve the submodule's contents. Managing submodules correctly is crucial for maintaining project integrity and ensuring consistent dependencies across different environments. When a submodule is updated in the main repository, only the commit ID is actually tracked so changes to the submodule repository must be committed, pushed, and then committed in the parent project to be included. If a submodule is updated on disk but not committed in the submodule repository, your working tree will reflect that it needs to be committed.

Submodules can be complex to manage, especially when dealing with nested submodules or frequent updates. Incorrect handling can lead to inconsistencies and difficulties when switching branches or collaborating with others. Be sure to commit changes made to submodules in the submodule and the parent repository.

Submodules can contain other submodules, creating nested submodule structures. Managing nested submodules requires careful attention to ensure proper initialization and updates at each level.

The .gitmodules file in the superproject's root directory defines the configuration for each submodule, including the path and URL of the external repository. This file is crucial for initializing and updating submodules correctly.

git(1), git-clone(1), gitmodules(5)