1GIT-SUBMODULE(1) Git Manual GIT-SUBMODULE(1)
2
6 git-submodule - Initialize, update or inspect submodules
7
9 git submodule [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
10 [--reference <repository>] [--] <repository> [<path>]
11 git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...]
12 git submodule [--quiet] init [--] [<path>...]
13 git submodule [--quiet] deinit [-f|--force] [--] <path>...
14 git submodule [--quiet] update [--init] [--remote] [-N|--no-fetch]
15 [-f|--force] [--rebase] [--reference <repository>]
16 [--merge] [--recursive] [--] [<path>...]
17 git submodule [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
18 [commit] [--] [<path>...]
19 git submodule [--quiet] foreach [--recursive] <command>
20 git submodule [--quiet] sync [--] [<path>...]
21
24 Submodules allow foreign repositories to be embedded within a dedicated
25 subdirectory of the source tree, always pointed at a particular commit.
26 They are not to be confused with remotes, which are meant mainly for
28 branches of the same project; submodules are meant for different
29 projects you would like to make part of your source tree, while the
30 history of the two projects still stays completely independent and you
31 cannot modify the contents of the submodule from within the main
32 project. If you want to merge the project histories and want to treat
33 the aggregated whole as a single project from then on, you may want to
34 add a remote for the other project and use the subtree merge strategy,
35 instead of treating the other project as a submodule. Directories that
36 come from both projects can be cloned and checked out as a whole if you
37 choose to go that route.
38 Submodules are composed from a so-called gitlink tree entry in the main
40 repository that refers to a particular commit object within the inner
41 repository that is completely separate. A record in the .gitmodules
42 (see gitmodules(5)) file at the root of the source tree assigns a
43 logical name to the submodule and describes the default URL the
44 submodule shall be cloned from. The logical name can be used for
45 overriding this URL within your local repository configuration (see
46 submodule init).
47 This command will manage the tree entries and contents of the
49 gitmodules file for you, as well as inspect the status of your
50 submodules and update them. When adding a new submodule to the tree,
51 the add subcommand is to be used. However, when pulling a tree
52 containing submodules, these will not be checked out by default; the
53 init and update subcommands will maintain submodules checked out and at
54 appropriate revision in your working tree. You can briefly inspect the
55 up-to-date status of your submodules using the status subcommand and
56 get a detailed overview of the difference between the index and
57 checkouts using the summary subcommand.
58
60 add
61 Add the given repository as a submodule at the given path to the
62 changeset to be committed next to the current project: the current
63 project is termed the "superproject".
64 This requires at least one argument: <repository>. The optional
66 argument <path> is the relative location for the cloned submodule
67 to exist in the superproject. If <path> is not given, the
68 "humanish" part of the source repository is used ("repo" for
69 "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). The <path>
70 is also used as the submodule’s logical name in its configuration
71 entries unless --name is used to specify a logical name.
72 <repository> is the URL of the new submodule’s origin repository.
74 This may be either an absolute URL, or (if it begins with ./ or
75 ../), the location relative to the superproject’s origin repository
76 (Please note that to specify a repository foo.git which is located
77 right next to a superproject bar.git, you’ll have to use ../foo.git
78 instead of ./foo.git - as one might expect when following the rules
79 for relative URLs - because the evaluation of relative URLs in Git
80 is identical to that of relative directories). If the superproject
81 doesn’t have an origin configured the superproject is its own
82 authoritative upstream and the current working directory is used
83 instead.
84 <path> is the relative location for the cloned submodule to exist
86 in the superproject. If <path> does not exist, then the submodule
87 is created by cloning from the named URL. If <path> does exist and
88 is already a valid Git repository, then this is added to the
89 changeset without cloning. This second form is provided to ease
90 creating a new submodule from scratch, and presumes the user will
91 later push the submodule to the given URL.
92 In either case, the given URL is recorded into .gitmodules for use
94 by subsequent users cloning the superproject. If the URL is given
95 relative to the superproject’s repository, the presumption is the
96 superproject and submodule repositories will be kept together in
97 the same relative location, and only the superproject’s URL needs
98 to be provided: git-submodule will correctly locate the submodule
99 using the relative URL in .gitmodules.
100 status
102 Show the status of the submodules. This will print the SHA-1 of the
103 currently checked out commit for each submodule, along with the
104 submodule path and the output of git describe for the SHA-1. Each
105 SHA-1 will be prefixed with - if the submodule is not initialized,
106 + if the currently checked out submodule commit does not match the
107 SHA-1 found in the index of the containing repository and U if the
108 submodule has merge conflicts.
109 If --recursive is specified, this command will recurse into nested
111 submodules, and show their status as well.
112 If you are only interested in changes of the currently initialized
114 submodules with respect to the commit recorded in the index or the
115 HEAD, git-status(1) and git-diff(1) will provide that information
116 too (and can also report changes to a submodule’s work tree).
117 init
119 Initialize the submodules recorded in the index (which were added
120 and committed elsewhere) by copying submodule names and urls from
121 .gitmodules to .git/config. Optional <path> arguments limit which
122 submodules will be initialized. It will also copy the value of
123 submodule.$name.update into .git/config. The key used in
124 .git/config is submodule.$name.url. This command does not alter
125 existing information in .git/config. You can then customize the
126 submodule clone URLs in .git/config for your local setup and
127 proceed to git submodule update; you can also just use git
128 submodule update --init without the explicit init step if you do
129 not intend to customize any submodule locations.
130 deinit
132 Unregister the given submodules, i.e. remove the whole
133 submodule.$name section from .git/config together with their work
134 tree. Further calls to git submodule update, git submodule foreach
135 and git submodule sync will skip any unregistered submodules until
136 they are initialized again, so use this command if you don’t want
137 to have a local checkout of the submodule in your work tree
138 anymore. If you really want to remove a submodule from the
139 repository and commit that use git-rm(1) instead.
140 If --force is specified, the submodule’s work tree will be removed
142 even if it contains local modifications.
143 update
145 Update the registered submodules, i.e. clone missing submodules and
146 checkout the commit specified in the index of the containing
147 repository. This will make the submodules HEAD be detached unless
148 --rebase or --merge is specified or the key submodule.$name.update
149 is set to rebase, merge or none. none can be overridden by
150 specifying --checkout.
151 If the submodule is not yet initialized, and you just want to use
153 the setting as stored in .gitmodules, you can automatically
154 initialize the submodule with the --init option.
155 If --recursive is specified, this command will recurse into the
157 registered submodules, and update any nested submodules within.
158 If --force is specified, the submodule will be checked out (using
160 git checkout --force if appropriate), even if the commit specified
161 in the index of the containing repository already matches the
162 commit checked out in the submodule.
163 summary
165 Show commit summary between the given commit (defaults to HEAD) and
166 working tree/index. For a submodule in question, a series of
167 commits in the submodule between the given super project commit and
168 the index or working tree (switched by --cached) are shown. If the
169 option --files is given, show the series of commits in the
170 submodule between the index of the super project and the working
171 tree of the submodule (this option doesn’t allow to use the
172 --cached option or to provide an explicit commit).
173 Using the --submodule=log option with git-diff(1) will provide that
175 information too.
176 foreach
178 Evaluates an arbitrary shell command in each checked out submodule.
179 The command has access to the variables $name, $path, $sha1 and
180 $toplevel: $name is the name of the relevant submodule section in
181 .gitmodules, $path is the name of the submodule directory relative
182 to the superproject, $sha1 is the commit as recorded in the
183 superproject, and $toplevel is the absolute path to the top-level
184 of the superproject. Any submodules defined in the superproject but
185 not checked out are ignored by this command. Unless given --quiet,
186 foreach prints the name of each submodule before evaluating the
187 command. If --recursive is given, submodules are traversed
188 recursively (i.e. the given shell command is evaluated in nested
189 submodules as well). A non-zero return from the command in any
190 submodule causes the processing to terminate. This can be
191 overridden by adding || : to the end of the command.
192 As an example, git submodule foreach 'echo $path `git rev-parse
194 HEAD`' will show the path and currently checked out commit for each
195 submodule.
196 sync
198 Synchronizes submodules' remote URL configuration setting to the
199 value specified in .gitmodules. It will only affect those
200 submodules which already have a URL entry in .git/config (that is
201 the case when they are initialized or freshly added). This is
202 useful when submodule URLs change upstream and you need to update
203 your local repositories accordingly.
204 "git submodule sync" synchronizes all submodules while "git
206 submodule sync -- A" synchronizes submodule "A" only.
207
209 -q, --quiet
210 Only print error messages.
211 -b, --branch
213 Branch of repository to add as submodule. The name of the branch is
214 recorded as submodule.<path>.branch in .gitmodules for update
215 --remote.
216 -f, --force
218 This option is only valid for add, deinit and update commands. When
219 running add, allow adding an otherwise ignored submodule path. When
220 running deinit the submodule work trees will be removed even if
221 they contain local changes. When running update, throw away local
222 changes in submodules when switching to a different commit; and
223 always run a checkout operation in the submodule, even if the
224 commit listed in the index of the containing repository matches the
225 commit checked out in the submodule.
226 --cached
228 This option is only valid for status and summary commands. These
229 commands typically use the commit found in the submodule HEAD, but
230 with this option, the commit stored in the index is used instead.
231 --files
233 This option is only valid for the summary command. This command
234 compares the commit in the index with that in the submodule HEAD
235 when this option is used.
236 -n, --summary-limit
238 This option is only valid for the summary command. Limit the
239 summary size (number of commits shown in total). Giving 0 will
240 disable the summary; a negative number means unlimited (the
241 default). This limit only applies to modified submodules. The size
242 is always limited to 1 for added/deleted/typechanged submodules.
243 --remote
245 This option is only valid for the update command. Instead of using
246 the superproject’s recorded SHA-1 to update the submodule, use the
247 status of the submodule’s remote tracking branch. The remote used
248 is branch’s remote (branch.<name>.remote), defaulting to origin.
249 The remote branch used defaults to master, but the branch name may
250 be overridden by setting the submodule.<name>.branch option in
251 either .gitmodules or .git/config (with .git/config taking
252 precedence).
253 This works for any of the supported update procedures (--checkout,
255 --rebase, etc.). The only change is the source of the target SHA-1.
256 For example, submodule update --remote --merge will merge upstream
257 submodule changes into the submodules, while submodule update
258 --merge will merge superproject gitlink changes into the
259 submodules.
260 In order to ensure a current tracking branch state, update --remote
262 fetches the submodule’s remote repository before calculating the
263 SHA-1. If you don’t want to fetch, you should use submodule update
264 --remote --no-fetch.
265 -N, --no-fetch
267 This option is only valid for the update command. Don’t fetch new
268 objects from the remote site.
269 --merge
271 This option is only valid for the update command. Merge the commit
272 recorded in the superproject into the current branch of the
273 submodule. If this option is given, the submodule’s HEAD will not
274 be detached. If a merge failure prevents this process, you will
275 have to resolve the resulting conflicts within the submodule with
276 the usual conflict resolution tools. If the key
277 submodule.$name.update is set to merge, this option is implicit.
278 --rebase
280 This option is only valid for the update command. Rebase the
281 current branch onto the commit recorded in the superproject. If
282 this option is given, the submodule’s HEAD will not be detached. If
283 a merge failure prevents this process, you will have to resolve
284 these failures with git-rebase(1). If the key
285 submodule.$name.update is set to rebase, this option is implicit.
286 --init
288 This option is only valid for the update command. Initialize all
289 submodules for which "git submodule init" has not been called so
290 far before updating.
291 --name
293 This option is only valid for the add command. It sets the
294 submodule’s name to the given string instead of defaulting to its
295 path. The name must be valid as a directory name and may not end
296 with a /.
297 --reference <repository>
299 This option is only valid for add and update commands. These
300 commands sometimes need to clone a remote repository. In this case,
301 this option will be passed to the git-clone(1) command.
302 NOTE: Do not use this option unless you have read the note for git-
304 clone(1)'s --reference and --shared options carefully.
305 --recursive
307 This option is only valid for foreach, update and status commands.
308 Traverse submodules recursively. The operation is performed not
309 only in the submodules of the current repo, but also in any nested
310 submodules inside those submodules (and so on).
311 <path>...
313 Paths to submodule(s). When specified this will restrict the
314 command to only operate on the submodules found at the specified
315 paths. (This argument is required with add).
316
318 When initializing submodules, a .gitmodules file in the top-level
319 directory of the containing repository is used to find the url of each
320 submodule. This file should be formatted in the same way as
321 $GIT_DIR/config. The key to each submodule url is
322 "submodule.$name.url". See gitmodules(5) for details.
323
325 Part of the git(1) suite
326Git 1.8.3.1 11/19/2018 GIT-SUBMODULE(1)