| gitmodules(5) |
| ============= |
| |
| NAME |
| ---- |
| gitmodules - defining submodule properties |
| |
| SYNOPSIS |
| -------- |
| $GIT_WORK_DIR/.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 linkgit:git-config[1]. |
| |
| The file contains one subsection per submodule, and the subsection value |
| is the name of the submodule. Each submodule section also contains the |
| following required keys: |
| |
| submodule.<name>.path:: |
| 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. |
| |
| submodule.<name>.url:: |
| Defines a URL from which the submodule repository can be cloned. |
| This may be either an absolute URL ready to be passed to |
| linkgit:git-clone[1] or (if it begins with ./ or ../) a location |
| relative to the superproject's origin repository. |
| |
| submodule.<name>.update:: |
| Defines what to do when the submodule is updated by the superproject. |
| If 'checkout' (the default), the new commit specified in the |
| superproject will be checked out in the submodule on a detached HEAD. |
| If 'rebase', the current branch of the submodule will be rebased onto |
| the commit specified in the superproject. If 'merge', the commit |
| specified in the superproject will be merged into the current branch |
| in the submodule. |
| If 'none', the submodule with name `$name` will not be updated |
| by default. |
| |
| This config option is overridden if 'git submodule update' is given |
| the '--merge', '--rebase' or '--checkout' options. |
| |
| submodule.<name>.fetchRecurseSubmodules:: |
| 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". |
| |
| submodule.<name>.ignore:: |
| Defines under what circumstances "git status" and the diff family show |
| a submodule as modified. When set to "all", it will never be considered |
| modified, "dirty" will ignore all changes to the submodules work tree and |
| takes only differences between the HEAD of the submodule and the commit |
| recorded in the superproject into account. "untracked" will additionally |
| let submodules with modified tracked files in their work tree show up. |
| Using "none" (the default when this option is not set) also shows |
| submodules that have untracked files in their work tree as changed. |
| 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 |
| "--ignore-submodule" option. |
| |
| |
| EXAMPLES |
| -------- |
| |
| Consider the following .gitmodules file: |
| |
| [submodule "libfoo"] |
| path = include/foo |
| url = git://foo.com/git/lib.git |
| |
| [submodule "libbar"] |
| path = include/bar |
| 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 |
| -------- |
| linkgit:git-submodule[1] linkgit:git-config[1] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |
