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.
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
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.
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
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 detachedHEADat 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 usegit submodule update --init --recursive. Settingsubmodule.recursemakes commands such ascheckout,pullandfetchfollow 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 overhttpsorsshare unaffected.--remotechanges the pointer. It fetches the tracked branch (submodule.<name>.branchin.gitmodules, defaultHEADof 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>, thengit rm <path>, and optionally delete.git/modules/<name>. - Shallow submodules.
--depth 1onaddorupdatesaves 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
.gitmodulesfile, see .gitmodules.