]>
Commit | Line | Data |
---|---|---|
1 | git-submodule(1) | |
2 | ================ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-submodule - Initialize, update or inspect submodules | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
11 | [verse] | |
12 | 'git submodule' [--quiet] add [-b branch] | |
13 | [--reference <repository>] [--] <repository> [<path>] | |
14 | 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] | |
15 | 'git submodule' [--quiet] init [--] [<path>...] | |
16 | 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] | |
17 | [--reference <repository>] [--merge] [--recursive] [--] [<path>...] | |
18 | 'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...] | |
19 | 'git submodule' [--quiet] foreach [--recursive] <command> | |
20 | 'git submodule' [--quiet] sync [--] [<path>...] | |
21 | ||
22 | ||
23 | DESCRIPTION | |
24 | ----------- | |
25 | Submodules allow foreign repositories to be embedded within | |
26 | a dedicated subdirectory of the source tree, always pointed | |
27 | at a particular commit. | |
28 | ||
29 | They are not to be confused with remotes, which are meant mainly | |
30 | for branches of the same project; submodules are meant for | |
31 | different projects you would like to make part of your source tree, | |
32 | while the history of the two projects still stays completely | |
33 | independent and you cannot modify the contents of the submodule | |
34 | from within the main project. | |
35 | If you want to merge the project histories and want to treat the | |
36 | aggregated whole as a single project from then on, you may want to | |
37 | add a remote for the other project and use the 'subtree' merge strategy, | |
38 | instead of treating the other project as a submodule. Directories | |
39 | that come from both projects can be cloned and checked out as a whole | |
40 | if you choose to go that route. | |
41 | ||
42 | Submodules are composed from a so-called `gitlink` tree entry | |
43 | in the main repository that refers to a particular commit object | |
44 | within the inner repository that is completely separate. | |
45 | A record in the `.gitmodules` file at the root of the source | |
46 | tree assigns a logical name to the submodule and describes | |
47 | the default URL the submodule shall be cloned from. | |
48 | The logical name can be used for overriding this URL within your | |
49 | local repository configuration (see 'submodule init'). | |
50 | ||
51 | This command will manage the tree entries and contents of the | |
52 | gitmodules file for you, as well as inspect the status of your | |
53 | submodules and update them. | |
54 | When adding a new submodule to the tree, the 'add' subcommand | |
55 | is to be used. However, when pulling a tree containing submodules, | |
56 | these will not be checked out by default; | |
57 | the 'init' and 'update' subcommands will maintain submodules | |
58 | checked out and at appropriate revision in your working tree. | |
59 | You can briefly inspect the up-to-date status of your submodules | |
60 | using the 'status' subcommand and get a detailed overview of the | |
61 | difference between the index and checkouts using the 'summary' | |
62 | subcommand. | |
63 | ||
64 | ||
65 | COMMANDS | |
66 | -------- | |
67 | add:: | |
68 | Add the given repository as a submodule at the given path | |
69 | to the changeset to be committed next to the current | |
70 | project: the current project is termed the "superproject". | |
71 | + | |
72 | This requires at least one argument: <repository>. The optional | |
73 | argument <path> is the relative location for the cloned submodule | |
74 | to exist in the superproject. If <path> is not given, the | |
75 | "humanish" part of the source repository is used ("repo" for | |
76 | "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). | |
77 | + | |
78 | <repository> is the URL of the new submodule's origin repository. | |
79 | This may be either an absolute URL, or (if it begins with ./ | |
80 | or ../), the location relative to the superproject's origin | |
81 | repository. | |
82 | + | |
83 | <path> is the relative location for the cloned submodule to | |
84 | exist in the superproject. If <path> does not exist, then the | |
85 | submodule is created by cloning from the named URL. If <path> does | |
86 | exist and is already a valid git repository, then this is added | |
87 | to the changeset without cloning. This second form is provided | |
88 | to ease creating a new submodule from scratch, and presumes | |
89 | the user will later push the submodule to the given URL. | |
90 | + | |
91 | In either case, the given URL is recorded into .gitmodules for | |
92 | use by subsequent users cloning the superproject. If the URL is | |
93 | given relative to the superproject's repository, the presumption | |
94 | is the superproject and submodule repositories will be kept | |
95 | together in the same relative location, and only the | |
96 | superproject's URL needs to be provided: git-submodule will correctly | |
97 | locate the submodule using the relative URL in .gitmodules. | |
98 | + | |
99 | The submodule will be added with "git add --force <path>". I.e. git | |
100 | doesn't care if the new path is in a `gitignore`. Your invocation of | |
101 | "git submodule add" is considered enough to override it. | |
102 | ||
103 | status:: | |
104 | Show the status of the submodules. This will print the SHA-1 of the | |
105 | currently checked out commit for each submodule, along with the | |
106 | submodule path and the output of 'git describe' for the | |
107 | SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not | |
108 | initialized and `+` if the currently checked out submodule commit | |
109 | does not match the SHA-1 found in the index of the containing | |
110 | repository. This command is the default command for 'git submodule'. | |
111 | + | |
112 | If '--recursive' is specified, this command will recurse into nested | |
113 | submodules, and show their status as well. | |
114 | ||
115 | init:: | |
116 | Initialize the submodules, i.e. register each submodule name | |
117 | and url found in .gitmodules into .git/config. | |
118 | The key used in .git/config is `submodule.$name.url`. | |
119 | This command does not alter existing information in .git/config. | |
120 | You can then customize the submodule clone URLs in .git/config | |
121 | for your local setup and proceed to `git submodule update`; | |
122 | you can also just use `git submodule update --init` without | |
123 | the explicit 'init' step if you do not intend to customize | |
124 | any submodule locations. | |
125 | ||
126 | update:: | |
127 | Update the registered submodules, i.e. clone missing submodules and | |
128 | checkout the commit specified in the index of the containing repository. | |
129 | This will make the submodules HEAD be detached unless '--rebase' or | |
130 | '--merge' is specified or the key `submodule.$name.update` is set to | |
131 | `rebase` or `merge`. | |
132 | + | |
133 | If the submodule is not yet initialized, and you just want to use the | |
134 | setting as stored in .gitmodules, you can automatically initialize the | |
135 | submodule with the --init option. | |
136 | + | |
137 | If '--recursive' is specified, this command will recurse into the | |
138 | registered submodules, and update any nested submodules within. | |
139 | ||
140 | summary:: | |
141 | Show commit summary between the given commit (defaults to HEAD) and | |
142 | working tree/index. For a submodule in question, a series of commits | |
143 | in the submodule between the given super project commit and the | |
144 | index or working tree (switched by --cached) are shown. If the option | |
145 | --files is given, show the series of commits in the submodule between | |
146 | the index of the super project and the working tree of the submodule | |
147 | (this option doesn't allow to use the --cached option or to provide an | |
148 | explicit commit). | |
149 | ||
150 | foreach:: | |
151 | Evaluates an arbitrary shell command in each checked out submodule. | |
152 | The command has access to the variables $name, $path, $sha1 and | |
153 | $toplevel: | |
154 | $name is the name of the relevant submodule section in .gitmodules, | |
155 | $path is the name of the submodule directory relative to the | |
156 | superproject, $sha1 is the commit as recorded in the superproject, | |
157 | and $toplevel is the absolute path to the top-level of the superproject. | |
158 | Any submodules defined in the superproject but not checked out are | |
159 | ignored by this command. Unless given --quiet, foreach prints the name | |
160 | of each submodule before evaluating the command. | |
161 | If --recursive is given, submodules are traversed recursively (i.e. | |
162 | the given shell command is evaluated in nested submodules as well). | |
163 | A non-zero return from the command in any submodule causes | |
164 | the processing to terminate. This can be overridden by adding '|| :' | |
165 | to the end of the command. | |
166 | + | |
167 | As an example, +git submodule foreach \'echo $path {backtick}git | |
168 | rev-parse HEAD{backtick}'+ will show the path and currently checked out | |
169 | commit for each submodule. | |
170 | ||
171 | sync:: | |
172 | Synchronizes submodules' remote URL configuration setting | |
173 | to the value specified in .gitmodules. This is useful when | |
174 | submodule URLs change upstream and you need to update your local | |
175 | repositories accordingly. | |
176 | + | |
177 | "git submodule sync" synchronizes all submodules while | |
178 | "git submodule sync -- A" synchronizes submodule "A" only. | |
179 | ||
180 | OPTIONS | |
181 | ------- | |
182 | -q:: | |
183 | --quiet:: | |
184 | Only print error messages. | |
185 | ||
186 | -b:: | |
187 | --branch:: | |
188 | Branch of repository to add as submodule. | |
189 | ||
190 | --cached:: | |
191 | This option is only valid for status and summary commands. These | |
192 | commands typically use the commit found in the submodule HEAD, but | |
193 | with this option, the commit stored in the index is used instead. | |
194 | ||
195 | --files:: | |
196 | This option is only valid for the summary command. This command | |
197 | compares the commit in the index with that in the submodule HEAD | |
198 | when this option is used. | |
199 | ||
200 | -n:: | |
201 | --summary-limit:: | |
202 | This option is only valid for the summary command. | |
203 | Limit the summary size (number of commits shown in total). | |
204 | Giving 0 will disable the summary; a negative number means unlimited | |
205 | (the default). This limit only applies to modified submodules. The | |
206 | size is always limited to 1 for added/deleted/typechanged submodules. | |
207 | ||
208 | -N:: | |
209 | --no-fetch:: | |
210 | This option is only valid for the update command. | |
211 | Don't fetch new objects from the remote site. | |
212 | ||
213 | --merge:: | |
214 | This option is only valid for the update command. | |
215 | Merge the commit recorded in the superproject into the current branch | |
216 | of the submodule. If this option is given, the submodule's HEAD will | |
217 | not be detached. If a merge failure prevents this process, you will | |
218 | have to resolve the resulting conflicts within the submodule with the | |
219 | usual conflict resolution tools. | |
220 | If the key `submodule.$name.update` is set to `merge`, this option is | |
221 | implicit. | |
222 | ||
223 | --rebase:: | |
224 | This option is only valid for the update command. | |
225 | Rebase the current branch onto the commit recorded in the | |
226 | superproject. If this option is given, the submodule's HEAD will not | |
227 | be detached. If a merge failure prevents this process, you will have | |
228 | to resolve these failures with linkgit:git-rebase[1]. | |
229 | If the key `submodule.$name.update` is set to `rebase`, this option is | |
230 | implicit. | |
231 | ||
232 | --reference <repository>:: | |
233 | This option is only valid for add and update commands. These | |
234 | commands sometimes need to clone a remote repository. In this case, | |
235 | this option will be passed to the linkgit:git-clone[1] command. | |
236 | + | |
237 | *NOTE*: Do *not* use this option unless you have read the note | |
238 | for linkgit:git-clone[1]'s --reference and --shared options carefully. | |
239 | ||
240 | --recursive:: | |
241 | This option is only valid for foreach, update and status commands. | |
242 | Traverse submodules recursively. The operation is performed not | |
243 | only in the submodules of the current repo, but also | |
244 | in any nested submodules inside those submodules (and so on). | |
245 | ||
246 | <path>...:: | |
247 | Paths to submodule(s). When specified this will restrict the command | |
248 | to only operate on the submodules found at the specified paths. | |
249 | (This argument is required with add). | |
250 | ||
251 | FILES | |
252 | ----- | |
253 | When initializing submodules, a .gitmodules file in the top-level directory | |
254 | of the containing repository is used to find the url of each submodule. | |
255 | This file should be formatted in the same way as `$GIT_DIR/config`. The key | |
256 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] | |
257 | for details. | |
258 | ||
259 | ||
260 | AUTHOR | |
261 | ------ | |
262 | Written by Lars Hjemli <hjemli@gmail.com> | |
263 | ||
264 | GIT | |
265 | --- | |
266 | Part of the linkgit:git[1] suite |