git-submodule

View existing submodules and the checked-out commit for each one

$ git submodule

$ git submodule update --init --recursive

$ git submodule add [repository_url]

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

$ git submodule update --remote

$ git submodule set-url [path/to/submodule] [new_url]

$ git submodule deinit [path/to/submodule]

git submodule [-q|--quiet] <command> [<args>]

-q, --quiet
    Suppress all output except errors

absorbgitdirs
    Move .git dirs of linked submodules into superproject

add
    Clone repo and add as submodule at path (<repo> [<path>])

deinit
    Unregister submodule(s) [<path>...]

foreach
    Run shell command in each submodule [<cmd> [<args>]]

init
    Init config of submodules in .gitmodules [-- <path>]

status
    Show status of submodules [--cached|--recursive] [<path>]

sync
    Sync config from .gitmodules [-- <path>]

update
    Update submodules to recorded commits [--init|--recursive] [<path>]

The git submodule command handles submodules, which embed one Git repository inside another (superproject) as a subdirectory, tracking a specific commit rather than a branch. This is useful for external dependencies like libraries.

Common workflow: Use add to clone and register a repo; commit the .gitmodules file and gitlink entry. On clone, run git submodule update --init --recursive to fetch and checkout commits, including nested submodules.

Key commands:
• init: Copy submodule config from .gitmodules to .git/config.
• update: Checkout the committed SHA-1 for each submodule.
• status: Display commit, path, and dirty status.
• foreach: Run a script in each checked-out submodule.
• deinit: Unregister and optionally delete a submodule.
• sync: Update .git/config URLs from .gitmodules.

To track latest changes, cd into submodule, update it, then commit new hash in superproject. Many Git commands support --recurse-submodules for automation. Submodules enhance modularity but require discipline to update.

Submodules pin exact commits; no auto-tracking of branches. Always commit .gitmodules changes. Update requires superproject commit of new hashes. Nested submodules need --recursive. Avoid moving submodules without deinit.

Use --recurse-submodules on git clone, update, status, etc., for nested handling.

[submodule "path"]
path = dir
url = https://repo
branch = main
Commit to share configs.

Introduced in Git 1.5.3 (Sep 2007) for basic support. Evolved with deinit (1.8.2, 2013), absorbgitdirs (2.18, 2018), clone (2.41, 2023). summary deprecated (2.13+). Usage grew for dependency management.

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