]>
Commit | Line | Data |
---|---|---|
891dbc6e LH |
1 | gitmodules(5) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitmodules - defining submodule properties | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
e5b5c1d2 | 10 | $GIT_WORK_DIR/.gitmodules |
891dbc6e LH |
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 | |
5162e697 | 18 | of linkgit:git-config[1]. |
891dbc6e LH |
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. | |
47dc5d5f JN |
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. | |
891dbc6e | 35 | |
32948425 JH |
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 | |
42b49178 JH |
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. | |
32948425 | 44 | This config option is overridden if 'git submodule update' is given |
42b49178 | 45 | the '--merge' or '--rebase' options. |
ca2cedba | 46 | |
302ad7a9 JL |
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. | |
3776ea9d | 59 | Both settings can be overridden on the command line by using the |
302ad7a9 JL |
60 | "--ignore-submodule" option. |
61 | ||
891dbc6e LH |
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 | -------- | |
5162e697 | 83 | linkgit:git-submodule[1] linkgit:git-config[1] |
891dbc6e LH |
84 | |
85 | DOCUMENTATION | |
86 | ------------- | |
87 | Documentation by Lars Hjemli <hjemli@gmail.com> | |
88 | ||
89 | GIT | |
90 | --- | |
9e1f0a85 | 91 | Part of the linkgit:git[1] suite |