# git-submodule(1) Manual Page

## NAME

git-submodule - Initialize, update or inspect submodules

## SYNOPSIS

git-submodule [--quiet] add [-b branch] [--] <repository> [<path>] git-submodule [--quiet] status [--cached] [--] [<path>…] git-submodule [--quiet] [init|update] [--] [<path>…]

## COMMANDS

add

  Add the given repository as a submodule at the given path to the changeset to be committed next. In particular, the repository is cloned at the specified path, added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. If the repository url begins with ./ or ../, it is stored as given but resolved as a relative path from the main project's url when cloning.

status

  Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the submodule path and the output of git-describe(1) for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing repository. This command is the default command for git-submodule.

init

  Initialize the submodules, i.e. register in .git/config each submodule name and url found in .gitmodules. The key used in .git/config is `submodule.$name.url`. This command does not alter existing information in .git/config.

update

  Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached.

## OPTIONS

-q, --quiet

  Only print error messages.

-b, --branch

  Branch of repository to add as submodule.

--cached

  Display the SHA-1 stored in the index, not the SHA-1 of the currently checked out submodule commit. This option is only valid for the status command.

<path>

  Path to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths.

## FILES

When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as `$GIT_DIR/config`. The key to each submodule url is "submodule.$name.url". See gitmodules(5) for details.

## AUTHOR

Written by Lars Hjemli <hjemli@gmail.com>

## GIT

Part of the git(7) suite