gitmodules(5)

NAME#

gitmodules - Defining submodule properties

SYNOPSIS#

$GIT_WORK_TREE/.gitmodules

DESCRIPTION#

The .gitmodules file, located in the top-level directory of a Git working tree, is a text file with a syntax matching the requirements of git-config(1).

The file contains one subsection per submodule, and the subsection value is the name of the submodule. The name is set to the path where the submodule has been added unless it was customized with the --name option of git submodule add. Each submodule section also contains the following required keys:

submodule.<name>.path

submodule.<name>.url

In addition, there are a number of optional keys:

submodule.<name>.update

submodule.<name>.branch

submodule.<name>.fetchRecurseSubmodules

submodule.<name>.ignore

all

dirty

untracked

none

If this option is also present in the submodule’s entry in .git/config of the superproject, the setting there will override the one found in .gitmodules.

Both settings can be overridden on the command line by using the --ignore-submodules option. The git submodule commands are not affected by this setting.

submodule.<name>.shallow

NOTES#

Git does not allow the .gitmodules file within a working tree to be a symbolic link, and will refuse to check out such a tree entry. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem, and helps Git reliably enforce security checks of the file contents.

EXAMPLES#

Consider the following .gitmodules file:

[submodule "libfoo"]
\n
        path = include/foo
\n
        url = git://foo.com/git/lib.git
[submodule "libbar"]
\n
        path = include/bar
\n
        url = git://bar.com/git/lib.git

This defines two submodules, libfoo and libbar. These are expected to be checked out in the paths include/foo and include/bar, and for both submodules a URL is specified which can be used for cloning the submodules.

SEE ALSO#

git-submodule(1), gitsubmodules(7), git-config(1)

GIT#

Part of the git(1) suite