Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GITMODULES(5)			  Git Manual			 GITMODULES(5)

       gitmodules - defining submodule properties


       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

       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:

	   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 /.	All submodule paths must be
	   unique within the .gitmodules file.

	   Defines a URL from which the	submodule repository can be cloned.
	   This	may be either an absolute URL ready to be passed to git-
	   clone(1) or (if it begins with ./ or	../) a location	relative to
	   the superproject's origin repository.

       In addition, there are a	number of optional keys:

	   Defines the default update procedure	for the	named submodule, i.e.
	   how the submodule is	updated	by "git	submodule update" command in
	   the superproject. This is only used by git submodule	init to
	   initialize the configuration	variable of the	same name. Allowed
	   values here are checkout, rebase, merge or none. See	description of
	   update command in git-submodule(1) for their	meaning. Note that the
	   !command form is intentionally ignored here for security reasons.

	   A remote branch name	for tracking updates in	the upstream
	   submodule. If the option is not specified, it defaults to master. A
	   special value of .  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 --remote documentation in git-
	   submodule(1)	for details.

	   This	option can be used to control recursive	fetching of this
	   submodule. If this option is	also present in	the submodules 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 "--[no-]recurse-submodules" option to
	   "git	fetch" and "git	pull".

	   Defines under what circumstances "git status" and the diff family
	   show	a submodule as modified. The following values are supported:

	       The submodule will never	be considered modified (but will
	       nonetheless show	up in the output of status and commit when it
	       has been	staged).

	       All changes to the submodule's work tree	will be	ignored, only
	       committed differences between the HEAD of the submodule and its
	       recorded	state in the superproject are taken into account.

	       Only untracked files in submodules will be ignored. Committed
	       differences and modifications to	tracked	files will show	up.

	       No modifiations to submodules are ignored, all of committed
	       differences, and	modifications to tracked and untracked files
	       are shown. This is the default option.

		   If this option is also present in the submodules entry in .git/config
		   of the superproject,	the setting there will override	the one	found in
		   Both	settings can be	overridden on the command line by using	the
		   "--ignore-submodule"	option.	The 'git submodule' commands are not
		   affected by this setting.

	   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.

       Consider	the following .gitmodules file:

	   [submodule "libfoo"]
		   path	= include/foo
		   url = git://

	   [submodule "libbar"]
		   path	= include/bar
		   url = 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

       git-submodule(1)	git-config(1)

       Part of the git(1) suite

Git 2.13.2			  06/24/2017			 GITMODULES(5)


Want to link to this manual page? Use this URL:

home | help