Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 1 | gitmodules(5) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitmodules - defining submodule properties |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
Gustaf Hendeby | e5b5c1d | 2008-08-31 18:00:27 +0200 | [diff] [blame] | 10 | $GIT_WORK_DIR/.gitmodules |
Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | The `.gitmodules` file, located in the top-level directory of a git |
| 17 | working tree, is a text file with a syntax matching the requirements |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 18 | of linkgit:git-config[1]. |
Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 19 | |
| 20 | The file contains one subsection per submodule, and the subsection value |
| 21 | is the name of the submodule. Each submodule section also contains the |
| 22 | following required keys: |
| 23 | |
| 24 | submodule.<name>.path:: |
| 25 | Defines the path, relative to the top-level directory of the git |
| 26 | working tree, where the submodule is expected to be checked out. |
| 27 | The path name must not end with a `/`. All submodule paths must |
| 28 | be unique within the .gitmodules file. |
| 29 | |
| 30 | submodule.<name>.url:: |
| 31 | Defines an url from where the submodule repository can be cloned. |
Jonathan Nieder | 47dc5d5 | 2010-07-15 02:41:55 -0500 | [diff] [blame] | 32 | This may be either an absolute URL ready to be passed to |
| 33 | linkgit:git-clone[1] or (if it begins with ./ or ../) a location |
| 34 | relative to the superproject's origin repository. |
Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 35 | |
Johan Herland | 3294842 | 2009-06-03 08:27:06 +0200 | [diff] [blame] | 36 | submodule.<name>.update:: |
| 37 | Defines what to do when the submodule is updated by the superproject. |
| 38 | If 'checkout' (the default), the new commit specified in the |
| 39 | superproject will be checked out in the submodule on a detached HEAD. |
| 40 | If 'rebase', the current branch of the submodule will be rebased onto |
Johan Herland | 42b4917 | 2009-06-03 00:59:12 +0200 | [diff] [blame] | 41 | the commit specified in the superproject. If 'merge', the commit |
| 42 | specified in the superproject will be merged into the current branch |
| 43 | in the submodule. |
Johan Herland | 3294842 | 2009-06-03 08:27:06 +0200 | [diff] [blame] | 44 | This config option is overridden if 'git submodule update' is given |
Johan Herland | 42b4917 | 2009-06-03 00:59:12 +0200 | [diff] [blame] | 45 | the '--merge' or '--rebase' options. |
Peter Hutterer | ca2cedb | 2009-04-24 09:06:38 +1000 | [diff] [blame] | 46 | |
Jens Lehmann | 302ad7a | 2010-08-06 00:40:48 +0200 | [diff] [blame] | 47 | submodule.<name>.ignore:: |
| 48 | Defines under what circumstances "git status" and the diff family show |
| 49 | a submodule as modified. When set to "all", it will never be considered |
| 50 | modified, "dirty" will ignore all changes to the submodules work tree and |
| 51 | takes only differences between the HEAD of the submodule and the commit |
| 52 | recorded in the superproject into account. "untracked" will additionally |
| 53 | let submodules with modified tracked files in their work tree show up. |
| 54 | Using "none" (the default when this option is not set) also shows |
| 55 | submodules that have untracked files in their work tree as changed. |
| 56 | If this option is also present in the submodules entry in .git/config of |
| 57 | the superproject, the setting there will override the one found in |
| 58 | .gitmodules. |
Ralf Wildenhues | 3776ea9 | 2010-08-22 13:12:12 +0200 | [diff] [blame] | 59 | Both settings can be overridden on the command line by using the |
Jens Lehmann | 302ad7a | 2010-08-06 00:40:48 +0200 | [diff] [blame] | 60 | "--ignore-submodule" option. |
| 61 | |
Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 62 | |
| 63 | EXAMPLES |
| 64 | -------- |
| 65 | |
| 66 | Consider the following .gitmodules file: |
| 67 | |
| 68 | [submodule "libfoo"] |
| 69 | path = include/foo |
| 70 | url = git://foo.com/git/lib.git |
| 71 | |
| 72 | [submodule "libbar"] |
| 73 | path = include/bar |
| 74 | url = git://bar.com/git/lib.git |
| 75 | |
| 76 | |
| 77 | This defines two submodules, `libfoo` and `libbar`. These are expected to |
| 78 | be checked out in the paths 'include/foo' and 'include/bar', and for both |
| 79 | submodules an url is specified which can be used for cloning the submodules. |
| 80 | |
| 81 | SEE ALSO |
| 82 | -------- |
Dan McGee | 5162e69 | 2007-12-29 00:20:38 -0600 | [diff] [blame] | 83 | linkgit:git-submodule[1] linkgit:git-config[1] |
Lars Hjemli | 891dbc6 | 2007-06-12 09:05:21 +0200 | [diff] [blame] | 84 | |
| 85 | DOCUMENTATION |
| 86 | ------------- |
| 87 | Documentation by Lars Hjemli <hjemli@gmail.com> |
| 88 | |
| 89 | GIT |
| 90 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 91 | Part of the linkgit:git[1] suite |