Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Remotes and Collaboration

git submodule command

Reference for git submodule: add, init, update, status, foreach, sync and deinit. Learn how a superproject pins another repository to an exact commit.

git submodule lets one repository (the superproject) contain another repository at a specific commit. The superproject does not store the other project's files in its own history. It stores a pointer: a special tree entry (mode 160000, a "gitlink") that holds a commit ID, plus a .gitmodules file that maps the path to a URL.

Because the pointer is an exact commit, everyone who checks out the superproject commit gets the same version of the dependency. The price is extra steps: submodules are not cloned, updated or committed automatically unless you ask for it.

Terminal
git submodule add [-b <branch>] [--name <name>] <url> [<path>]
git submodule update --init [--recursive] [--remote] [<path>...]
git submodule status | foreach | sync | deinit | absorbgitdirs | summary

Try it

Bash Add a submodule and clone it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Move the pointer to a newer commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git submodule [--quiet] add [-b <branch>] [-f] [--name <name>] [--depth <n>] [--] <repository> [<path>]
git submodule [--quiet] update [--init] [--remote] [--recursive] [--checkout|--merge|--rebase] [--depth <n>] [--] [<path>...]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>...]
git submodule [--quiet] deinit [-f | --force] (--all | [--] <path>...)
Subcommand Description
add Clones the repository into <path>, records it in .gitmodules and stages both the file and the gitlink. The path defaults to the repository's base name.
init Copies the URL from .gitmodules into .git/config. This is the step that "registers" a submodule locally.
update Checks out the commit recorded in the superproject. With --init it registers first; with --remote it follows the submodule's tracked branch instead.
status Prints one line per submodule: a prefix, the commit ID, the path and a description.
foreach Runs a shell command in each checked-out submodule. Variables $name, $sm_path, $displaypath, $sha1 and $toplevel are set.
sync Copies URLs from .gitmodules to .git/config and to each submodule's origin after a URL change.
deinit Unregisters a submodule and empties its working tree. The gitlink and .gitmodules entry stay.
absorbgitdirs Moves a nested .git directory into the superproject's .git/modules.
summary Shows the commits between the recorded pointer and HEAD of each submodule.

Status prefixes: a space means the checked-out commit matches the pointer, - means not initialized, + means the checked-out commit differs from the pointer, and U means merge conflicts.

Exit status: 0 on success; non-zero if any operation fails, including a failing foreach command.

Usage notes

  • Detached HEAD. After update, a submodule is on a detached HEAD at the recorded commit. Create or switch to a branch before committing inside it, or the commit becomes easy to lose.
  • Two commits, two repositories. A change in a submodule needs a commit and push in the submodule, then a commit in the superproject that records the new pointer. Push the submodule first, or teammates will receive a pointer to a commit that does not exist for them.
  • Cloning. git clone --recurse-submodules <url> clones and initializes everything. For an existing clone use git submodule update --init --recursive. Setting submodule.recurse makes commands such as checkout, pull and fetch follow submodules too (see submodule.* settings).
  • protocol.file.allow. Since Git 2.38.1, cloning a submodule from a local path is blocked by default as a security fix. Local examples need -c protocol.file.allow=always; real remotes over https or ssh are unaffected.
  • --remote changes the pointer. It fetches the tracked branch (submodule.<name>.branch in .gitmodules, default HEAD of the remote) and checks it out. The superproject then shows the submodule as modified, and you decide whether to commit that.
  • Removing a submodule takes several steps: git submodule deinit <path>, then git rm <path>, and optionally delete .git/modules/<name>.
  • Shallow submodules. --depth 1 on add or update saves bandwidth, but the pinned commit must be reachable from the fetched history.
  • Alternatives. If you want the other project's files inside your own history, use git subtree. To record the layout of a .gitmodules file, see .gitmodules.