'\" t
.\" Title: gitmodules
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 01/05/2024
.\" Manual: Git Manual
.\" Source: Git 2.43.0.381.gb435a96ce8
.\" Language: English
.\"
.TH "GITMODULES" "5" "01/05/2024" "Git 2\&.43\&.0\&.381\&.gb435a9" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gitmodules \- Defining submodule properties
.SH "SYNOPSIS"
.sp
$GIT_WORK_TREE/\&.gitmodules
.SH "DESCRIPTION"
.sp
The \fB\&.gitmodules\fR file, located in the top\-level directory of a Git working tree, is a text file with a syntax matching the requirements of \fBgit-config\fR(1)\&.
.sp
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 \fB\-\-name\fR option of \fIgit submodule add\fR\&. Each submodule section also contains the following required keys:
.PP
submodule\&.\&.path
.RS 4
Defines the path, relative to the top\-level directory of the Git working tree, where the submodule is expected to be checked out\&. The path name must not end with a
\fB/\fR\&. All submodule paths must be unique within the
\fB\&.gitmodules\fR
file\&.
.RE
.PP
submodule\&.\&.url
.RS 4
Defines a URL from which the submodule repository can be cloned\&. This may be either an absolute URL ready to be passed to
\fBgit-clone\fR(1)
or (if it begins with
\fB\&./\fR
or
\fB\&.\&./\fR) a location relative to the superproject\(cqs origin repository\&.
.RE
.sp
In addition, there are a number of optional keys:
.PP
submodule\&.\&.update
.RS 4
Defines the default update procedure for the named submodule, i\&.e\&. how the submodule is updated by the
\fBgit submodule update\fR
command in the superproject\&. This is only used by
\fBgit submodule init\fR
to initialize the configuration variable of the same name\&. Allowed values here are
\fIcheckout\fR,
\fIrebase\fR,
\fImerge\fR
or
\fInone\fR, but not
\fI!command\fR
(for security reasons)\&. See the description of the
\fIupdate\fR
command in
\fBgit-submodule\fR(1)
for more details\&.
.RE
.PP
submodule\&.\&.branch
.RS 4
A remote branch name for tracking updates in the upstream submodule\&. If the option is not specified, it defaults to the remote
\fBHEAD\fR\&. A special value of
\fB\&.\fR
is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository\&. See the
\fB\-\-remote\fR
documentation in
\fBgit-submodule\fR(1)
for details\&.
.RE
.PP
submodule\&.\&.fetchRecurseSubmodules
.RS 4
This option can be used to control recursive fetching of this submodule\&. If this option is also present in the submodule\(cqs entry in
\fB\&.git/config\fR
of the superproject, the setting there will override the one found in
\fB\&.gitmodules\fR\&. Both settings can be overridden on the command line by using the
\fB\-\-[no\-]recurse\-submodules\fR
option to
\fBgit fetch\fR
and
\fBgit pull\fR\&.
.RE
.PP
submodule\&.\&.ignore
.RS 4
Defines under what circumstances
\fBgit status\fR
and the diff family show a submodule as modified\&. The following values are supported:
.PP
all
.RS 4
The submodule will never be considered modified (but will nonetheless show up in the output of status and commit when it has been staged)\&.
.RE
.PP
dirty
.RS 4
All changes to the submodule\(cqs work tree will be ignored, only committed differences between the
\fBHEAD\fR
of the submodule and its recorded state in the superproject are taken into account\&.
.RE
.PP
untracked
.RS 4
Only untracked files in submodules will be ignored\&. Committed differences and modifications to tracked files will show up\&.
.RE
.PP
none
.RS 4
No modifications to submodules are ignored, all of committed differences, and modifications to tracked and untracked files are shown\&. This is the default option\&.
.RE
.sp
If this option is also present in the submodule\(cqs entry in
\fB\&.git/config\fR
of the superproject, the setting there will override the one found in
\fB\&.gitmodules\fR\&.
.sp
Both settings can be overridden on the command line by using the
\fB\-\-ignore\-submodules\fR
option\&. The
\fBgit submodule\fR
commands are not affected by this setting\&.
.RE
.PP
submodule\&.\&.shallow
.RS 4
When set to true, a clone of this submodule will be performed as a shallow clone (with a history depth of 1) unless the user explicitly asks for a non\-shallow clone\&.
.RE
.SH "NOTES"
.sp
Git does not allow the \fB\&.gitmodules\fR 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\&.
.SH "EXAMPLES"
.sp
Consider the following \fB\&.gitmodules\fR file:
.sp
.if n \{\
.RS 4
.\}
.nf
[submodule "libfoo"]
path = include/foo
url = git://foo\&.com/git/lib\&.git
[submodule "libbar"]
path = include/bar
url = git://bar\&.com/git/lib\&.git
.fi
.if n \{\
.RE
.\}
.sp
.sp
This defines two submodules, \fBlibfoo\fR and \fBlibbar\fR\&. These are expected to be checked out in the paths \fBinclude/foo\fR and \fBinclude/bar\fR, and for both submodules a URL is specified which can be used for cloning the submodules\&.
.SH "SEE ALSO"
.sp
\fBgit-submodule\fR(1), \fBgitsubmodules\fR(7), \fBgit-config\fR(1)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite