]>
Commit | Line | Data |
---|---|---|
891dbc6e LH |
1 | gitmodules(5) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
1b81d8cb | 6 | gitmodules - Defining submodule properties |
891dbc6e LH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
e5b5c1d2 | 10 | $GIT_WORK_DIR/.gitmodules |
891dbc6e LH |
11 | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
2de9b711 | 16 | The `.gitmodules` file, located in the top-level directory of a Git |
891dbc6e | 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 | |
73b0898d | 21 | is the name of the submodule. The name is set to the path where the |
bcf9626a | 22 | submodule has been added unless it was customized with the `--name` |
73b0898d | 23 | option of 'git submodule add'. Each submodule section also contains the |
891dbc6e LH |
24 | following required keys: |
25 | ||
26 | submodule.<name>.path:: | |
2de9b711 | 27 | Defines the path, relative to the top-level directory of the Git |
891dbc6e LH |
28 | working tree, where the submodule is expected to be checked out. |
29 | The path name must not end with a `/`. All submodule paths must | |
30 | be unique within the .gitmodules file. | |
31 | ||
32 | submodule.<name>.url:: | |
a7793a74 | 33 | Defines a URL from which the submodule repository can be cloned. |
47dc5d5f JN |
34 | This may be either an absolute URL ready to be passed to |
35 | linkgit:git-clone[1] or (if it begins with ./ or ../) a location | |
36 | relative to the superproject's origin repository. | |
891dbc6e | 37 | |
43fda945 TK |
38 | In addition, there are a number of optional keys: |
39 | ||
32948425 | 40 | submodule.<name>.update:: |
5c31acfb MS |
41 | Defines the default update procedure for the named submodule, |
42 | i.e. how the submodule is updated by "git submodule update" | |
43 | command in the superproject. This is only used by `git | |
44 | submodule init` to initialize the configuration variable of | |
45 | the same name. Allowed values here are 'checkout', 'rebase', | |
46 | 'merge' or 'none'. See description of 'update' command in | |
47 | linkgit:git-submodule[1] for their meaning. Note that the | |
48 | '!command' form is intentionally ignored here for security | |
49 | reasons. | |
ca2cedba | 50 | |
06b1abb5 TK |
51 | submodule.<name>.branch:: |
52 | A remote branch name for tracking updates in the upstream submodule. | |
15ef7800 BW |
53 | If the option is not specified, it defaults to 'master'. A special |
54 | value of `.` is used to indicate that the name of the branch in the | |
55 | submodule should be the same name as the current branch in the | |
56 | current repository. See the `--remote` documentation in | |
57 | linkgit:git-submodule[1] for details. | |
06b1abb5 | 58 | |
c1a3c364 | 59 | submodule.<name>.fetchRecurseSubmodules:: |
bf42b384 | 60 | This option can be used to control recursive fetching of this |
c1a3c364 JL |
61 | submodule. If this option is also present in the submodules entry in |
62 | .git/config of the superproject, the setting there will override the | |
63 | one found in .gitmodules. | |
469bfc96 | 64 | Both settings can be overridden on the command line by using the |
bf42b384 | 65 | "--[no-]recurse-submodules" option to "git fetch" and "git pull". |
c1a3c364 | 66 | |
302ad7a9 JL |
67 | submodule.<name>.ignore:: |
68 | Defines under what circumstances "git status" and the diff family show | |
61e28242 | 69 | a submodule as modified. The following values are supported: |
ad471949 AH |
70 | + |
71 | -- | |
61e28242 SS |
72 | all;; The submodule will never be considered modified (but will |
73 | nonetheless show up in the output of status and commit when it has | |
74 | been staged). | |
75 | ||
76 | dirty;; All changes to the submodule's work tree will be ignored, only | |
77 | committed differences between the HEAD of the submodule and its | |
78 | recorded state in the superproject are taken into account. | |
79 | ||
80 | untracked;; Only untracked files in submodules will be ignored. | |
81 | Committed differences and modifications to tracked files will show | |
82 | up. | |
83 | ||
84 | none;; No modifiations to submodules are ignored, all of committed | |
85 | differences, and modifications to tracked and untracked files are | |
86 | shown. This is the default option. | |
87 | ||
ad471949 AH |
88 | If this option is also present in the submodules entry in .git/config |
89 | of the superproject, the setting there will override the one found in | |
90 | .gitmodules. | |
91 | ||
92 | Both settings can be overridden on the command line by using the | |
0d4304c1 | 93 | "--ignore-submodules" option. The 'git submodule' commands are not |
ad471949 AH |
94 | affected by this setting. |
95 | -- | |
302ad7a9 | 96 | |
f6fb30a0 SB |
97 | submodule.<name>.shallow:: |
98 | When set to true, a clone of this submodule will be performed as a | |
8d3047cd SS |
99 | shallow clone (with a history depth of 1) unless the user explicitly |
100 | asks for a non-shallow clone. | |
f6fb30a0 | 101 | |
891dbc6e LH |
102 | |
103 | EXAMPLES | |
104 | -------- | |
105 | ||
106 | Consider the following .gitmodules file: | |
107 | ||
1925fe0c MÅ |
108 | ---- |
109 | [submodule "libfoo"] | |
110 | path = include/foo | |
111 | url = git://foo.com/git/lib.git | |
891dbc6e | 112 | |
1925fe0c MÅ |
113 | [submodule "libbar"] |
114 | path = include/bar | |
115 | url = git://bar.com/git/lib.git | |
116 | ---- | |
891dbc6e LH |
117 | |
118 | This defines two submodules, `libfoo` and `libbar`. These are expected to | |
68ed71b5 | 119 | be checked out in the paths `include/foo` and `include/bar`, and for both |
a7793a74 | 120 | submodules a URL is specified which can be used for cloning the submodules. |
891dbc6e LH |
121 | |
122 | SEE ALSO | |
123 | -------- | |
5162e697 | 124 | linkgit:git-submodule[1] linkgit:git-config[1] |
891dbc6e | 125 | |
891dbc6e LH |
126 | GIT |
127 | --- | |
9e1f0a85 | 128 | Part of the linkgit:git[1] suite |