1git-submodule(1) 2================ 3 4NAME 5---- 6git-submodule - Initialize, update or inspect submodules 7 8 9SYNOPSIS 10-------- 11[verse] 12'git submodule' [--quiet] add [<options>] [--] <repository> [<path>] 13'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 14'git submodule' [--quiet] init [--] [<path>...] 15'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 16'git submodule' [--quiet] update [<options>] [--] [<path>...] 17'git submodule' [--quiet] summary [<options>] [--] [<path>...] 18'git submodule' [--quiet] foreach [--recursive] <command> 19'git submodule' [--quiet] sync [--recursive] [--] [<path>...] 20'git submodule' [--quiet] absorbgitdirs [--] [<path>...] 21 22 23DESCRIPTION 24----------- 25Inspects, updates and manages submodules. 26 27A submodule allows you to keep another Git repository in a subdirectory 28of your repository. The other repository has its own history, which does not 29interfere with the history of the current repository. This can be used to 30have external dependencies such as third party libraries for example. 31 32When cloning or pulling a repository containing submodules however, 33these will not be checked out by default; the 'init' and 'update' 34subcommands will maintain submodules checked out and at 35appropriate revision in your working tree. 36 37Submodules are composed from a so-called `gitlink` tree entry 38in the main repository that refers to a particular commit object 39within the inner repository that is completely separate. 40A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the 41root of the source tree assigns a logical name to the submodule and 42describes the default URL the submodule shall be cloned from. 43The logical name can be used for overriding this URL within your 44local repository configuration (see 'submodule init'). 45 46Submodules are not to be confused with remotes, which are other 47repositories of the same project; submodules are meant for 48different projects you would like to make part of your source tree, 49while the history of the two projects still stays completely 50independent and you cannot modify the contents of the submodule 51from within the main project. 52If you want to merge the project histories and want to treat the 53aggregated whole as a single project from then on, you may want to 54add a remote for the other project and use the 'subtree' merge strategy, 55instead of treating the other project as a submodule. Directories 56that come from both projects can be cloned and checked out as a whole 57if you choose to go that route. 58 59COMMANDS 60-------- 61add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: 62 Add the given repository as a submodule at the given path 63 to the changeset to be committed next to the current 64 project: the current project is termed the "superproject". 65+ 66<repository> is the URL of the new submodule's origin repository. 67This may be either an absolute URL, or (if it begins with ./ 68or ../), the location relative to the superproject's default remote 69repository (Please note that to specify a repository 'foo.git' 70which is located right next to a superproject 'bar.git', you'll 71have to use '../foo.git' instead of './foo.git' - as one might expect 72when following the rules for relative URLs - because the evaluation 73of relative URLs in Git is identical to that of relative directories). 74+ 75The default remote is the remote of the remote tracking branch 76of the current branch. If no such remote tracking branch exists or 77the HEAD is detached, "origin" is assumed to be the default remote. 78If the superproject doesn't have a default remote configured 79the superproject is its own authoritative upstream and the current 80working directory is used instead. 81+ 82The optional argument <path> is the relative location for the cloned 83submodule to exist in the superproject. If <path> is not given, the 84canonical part of the source repository is used ("repo" for 85"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path> 86exists and is already a valid Git repository, then it is staged 87for commit without cloning. The <path> is also used as the submodule's 88logical name in its configuration entries unless `--name` is used 89to specify a logical name. 90+ 91The given URL is recorded into `.gitmodules` for use by subsequent users 92cloning the superproject. If the URL is given relative to the 93superproject's repository, the presumption is the superproject and 94submodule repositories will be kept together in the same relative 95location, and only the superproject's URL needs to be provided. 96git-submodule will correctly locate the submodule using the relative 97URL in `.gitmodules`. 98 99status [--cached] [--recursive] [--] [<path>...]:: 100 Show the status of the submodules. This will print the SHA-1 of the 101 currently checked out commit for each submodule, along with the 102 submodule path and the output of 'git describe' for the 103 SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not 104 initialized, `+` if the currently checked out submodule commit 105 does not match the SHA-1 found in the index of the containing 106 repository and `U` if the submodule has merge conflicts. 107+ 108If `--recursive` is specified, this command will recurse into nested 109submodules, and show their status as well. 110+ 111If you are only interested in changes of the currently initialized 112submodules with respect to the commit recorded in the index or the HEAD, 113linkgit:git-status[1] and linkgit:git-diff[1] will provide that information 114too (and can also report changes to a submodule's work tree). 115 116init [--] [<path>...]:: 117 Initialize the submodules recorded in the index (which were 118 added and committed elsewhere) by setting `submodule.$name.url` 119 in .git/config. It uses the same setting from `.gitmodules` as 120 a template. If the URL is relative, it will be resolved using 121 the default remote. If there is no default remote, the current 122 repository will be assumed to be upstream. 123+ 124Optional <path> arguments limit which submodules will be initialized. 125If no path is specified and submodule.active has been configured, submodules 126configured to be active will be initialized, otherwise all submodules are 127initialized. 128+ 129When present, it will also copy the value of `submodule.$name.update`. 130This command does not alter existing information in .git/config. 131You can then customize the submodule clone URLs in .git/config 132for your local setup and proceed to `git submodule update`; 133you can also just use `git submodule update --init` without 134the explicit 'init' step if you do not intend to customize 135any submodule locations. 136+ 137See the add subcommand for the definition of default remote. 138 139deinit [-f|--force] (--all|[--] <path>...):: 140 Unregister the given submodules, i.e. remove the whole 141 `submodule.$name` section from .git/config together with their work 142 tree. Further calls to `git submodule update`, `git submodule foreach` 143 and `git submodule sync` will skip any unregistered submodules until 144 they are initialized again, so use this command if you don't want to 145 have a local checkout of the submodule in your working tree anymore. If 146 you really want to remove a submodule from the repository and commit 147 that use linkgit:git-rm[1] instead. 148+ 149When the command is run without pathspec, it errors out, 150instead of deinit-ing everything, to prevent mistakes. 151+ 152If `--force` is specified, the submodule's working tree will 153be removed even if it contains local modifications. 154 155update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]:: 156+ 157-- 158Update the registered submodules to match what the superproject 159expects by cloning missing submodules and updating the working tree of 160the submodules. The "updating" can be done in several ways depending 161on command line options and the value of `submodule.<name>.update` 162configuration variable. The command line option takes precedence over 163the configuration variable. if neither is given, a checkout is performed. 164update procedures supported both from the command line as well as setting 165`submodule.<name>.update`: 166 167 checkout;; the commit recorded in the superproject will be 168 checked out in the submodule on a detached HEAD. 169+ 170If `--force` is specified, the submodule will be checked out (using 171`git checkout --force` if appropriate), even if the commit specified 172in the index of the containing repository already matches the commit 173checked out in the submodule. 174 175 rebase;; the current branch of the submodule will be rebased 176 onto the commit recorded in the superproject. 177 178 merge;; the commit recorded in the superproject will be merged 179 into the current branch in the submodule. 180 181The following procedures are only available via the `submodule.<name>.update` 182configuration variable: 183 184 custom command;; arbitrary shell command that takes a single 185 argument (the sha1 of the commit recorded in the 186 superproject) is executed. When `submodule.<name>.update` 187 is set to '!command', the remainder after the exclamation mark 188 is the custom command. 189 190 none;; the submodule is not updated. 191 192If the submodule is not yet initialized, and you just want to use the 193setting as stored in `.gitmodules`, you can automatically initialize the 194submodule with the `--init` option. 195 196If `--recursive` is specified, this command will recurse into the 197registered submodules, and update any nested submodules within. 198-- 199summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:: 200 Show commit summary between the given commit (defaults to HEAD) and 201 working tree/index. For a submodule in question, a series of commits 202 in the submodule between the given super project commit and the 203 index or working tree (switched by `--cached`) are shown. If the option 204 `--files` is given, show the series of commits in the submodule between 205 the index of the super project and the working tree of the submodule 206 (this option doesn't allow to use the `--cached` option or to provide an 207 explicit commit). 208+ 209Using the `--submodule=log` option with linkgit:git-diff[1] will provide that 210information too. 211 212foreach [--recursive] <command>:: 213 Evaluates an arbitrary shell command in each checked out submodule. 214 The command has access to the variables $name, $path, $sha1 and 215 $toplevel: 216 $name is the name of the relevant submodule section in `.gitmodules`, 217 $path is the name of the submodule directory relative to the 218 superproject, $sha1 is the commit as recorded in the superproject, 219 and $toplevel is the absolute path to the top-level of the superproject. 220 Any submodules defined in the superproject but not checked out are 221 ignored by this command. Unless given `--quiet`, foreach prints the name 222 of each submodule before evaluating the command. 223 If `--recursive` is given, submodules are traversed recursively (i.e. 224 the given shell command is evaluated in nested submodules as well). 225 A non-zero return from the command in any submodule causes 226 the processing to terminate. This can be overridden by adding '|| :' 227 to the end of the command. 228+ 229As an example, the command below will show the path and currently 230checked out commit for each submodule: 231+ 232-------------- 233git submodule foreach 'echo $path `git rev-parse HEAD`' 234-------------- 235 236sync [--recursive] [--] [<path>...]:: 237 Synchronizes submodules' remote URL configuration setting 238 to the value specified in `.gitmodules`. It will only affect those 239 submodules which already have a URL entry in .git/config (that is the 240 case when they are initialized or freshly added). This is useful when 241 submodule URLs change upstream and you need to update your local 242 repositories accordingly. 243+ 244"git submodule sync" synchronizes all submodules while 245"git submodule sync \-- A" synchronizes submodule "A" only. 246+ 247If `--recursive` is specified, this command will recurse into the 248registered submodules, and sync any nested submodules within. 249 250absorbgitdirs:: 251 If a git directory of a submodule is inside the submodule, 252 move the git directory of the submodule into its superprojects 253 `$GIT_DIR/modules` path and then connect the git directory and 254 its working directory by setting the `core.worktree` and adding 255 a .git file pointing to the git directory embedded in the 256 superprojects git directory. 257+ 258A repository that was cloned independently and later added as a submodule or 259old setups have the submodules git directory inside the submodule instead of 260embedded into the superprojects git directory. 261+ 262This command is recursive by default. 263 264OPTIONS 265------- 266-q:: 267--quiet:: 268 Only print error messages. 269 270--all:: 271 This option is only valid for the deinit command. Unregister all 272 submodules in the working tree. 273 274-b:: 275--branch:: 276 Branch of repository to add as submodule. 277 The name of the branch is recorded as `submodule.<name>.branch` in 278 `.gitmodules` for `update --remote`. A special value of `.` is used to 279 indicate that the name of the branch in the submodule should be the 280 same name as the current branch in the current repository. 281 282-f:: 283--force:: 284 This option is only valid for add, deinit and update commands. 285 When running add, allow adding an otherwise ignored submodule path. 286 When running deinit the submodule working trees will be removed even 287 if they contain local changes. 288 When running update (only effective with the checkout procedure), 289 throw away local changes in submodules when switching to a 290 different commit; and always run a checkout operation in the 291 submodule, even if the commit listed in the index of the 292 containing repository matches the commit checked out in the 293 submodule. 294 295--cached:: 296 This option is only valid for status and summary commands. These 297 commands typically use the commit found in the submodule HEAD, but 298 with this option, the commit stored in the index is used instead. 299 300--files:: 301 This option is only valid for the summary command. This command 302 compares the commit in the index with that in the submodule HEAD 303 when this option is used. 304 305-n:: 306--summary-limit:: 307 This option is only valid for the summary command. 308 Limit the summary size (number of commits shown in total). 309 Giving 0 will disable the summary; a negative number means unlimited 310 (the default). This limit only applies to modified submodules. The 311 size is always limited to 1 for added/deleted/typechanged submodules. 312 313--remote:: 314 This option is only valid for the update command. Instead of using 315 the superproject's recorded SHA-1 to update the submodule, use the 316 status of the submodule's remote-tracking branch. The remote used 317 is branch's remote (`branch.<name>.remote`), defaulting to `origin`. 318 The remote branch used defaults to `master`, but the branch name may 319 be overridden by setting the `submodule.<name>.branch` option in 320 either `.gitmodules` or `.git/config` (with `.git/config` taking 321 precedence). 322+ 323This works for any of the supported update procedures (`--checkout`, 324`--rebase`, etc.). The only change is the source of the target SHA-1. 325For example, `submodule update --remote --merge` will merge upstream 326submodule changes into the submodules, while `submodule update 327--merge` will merge superproject gitlink changes into the submodules. 328+ 329In order to ensure a current tracking branch state, `update --remote` 330fetches the submodule's remote repository before calculating the 331SHA-1. If you don't want to fetch, you should use `submodule update 332--remote --no-fetch`. 333+ 334Use this option to integrate changes from the upstream subproject with 335your submodule's current HEAD. Alternatively, you can run `git pull` 336from the submodule, which is equivalent except for the remote branch 337name: `update --remote` uses the default upstream repository and 338`submodule.<name>.branch`, while `git pull` uses the submodule's 339`branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want 340to distribute the default upstream branch with the superproject and 341`branch.<name>.merge` if you want a more native feel while working in 342the submodule itself. 343 344-N:: 345--no-fetch:: 346 This option is only valid for the update command. 347 Don't fetch new objects from the remote site. 348 349--checkout:: 350 This option is only valid for the update command. 351 Checkout the commit recorded in the superproject on a detached HEAD 352 in the submodule. This is the default behavior, the main use of 353 this option is to override `submodule.$name.update` when set to 354 a value other than `checkout`. 355 If the key `submodule.$name.update` is either not explicitly set or 356 set to `checkout`, this option is implicit. 357 358--merge:: 359 This option is only valid for the update command. 360 Merge the commit recorded in the superproject into the current branch 361 of the submodule. If this option is given, the submodule's HEAD will 362 not be detached. If a merge failure prevents this process, you will 363 have to resolve the resulting conflicts within the submodule with the 364 usual conflict resolution tools. 365 If the key `submodule.$name.update` is set to `merge`, this option is 366 implicit. 367 368--rebase:: 369 This option is only valid for the update command. 370 Rebase the current branch onto the commit recorded in the 371 superproject. If this option is given, the submodule's HEAD will not 372 be detached. If a merge failure prevents this process, you will have 373 to resolve these failures with linkgit:git-rebase[1]. 374 If the key `submodule.$name.update` is set to `rebase`, this option is 375 implicit. 376 377--init:: 378 This option is only valid for the update command. 379 Initialize all submodules for which "git submodule init" has not been 380 called so far before updating. 381 382--name:: 383 This option is only valid for the add command. It sets the submodule's 384 name to the given string instead of defaulting to its path. The name 385 must be valid as a directory name and may not end with a '/'. 386 387--reference <repository>:: 388 This option is only valid for add and update commands. These 389 commands sometimes need to clone a remote repository. In this case, 390 this option will be passed to the linkgit:git-clone[1] command. 391+ 392*NOTE*: Do *not* use this option unless you have read the note 393for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. 394 395--recursive:: 396 This option is only valid for foreach, update, status and sync commands. 397 Traverse submodules recursively. The operation is performed not 398 only in the submodules of the current repo, but also 399 in any nested submodules inside those submodules (and so on). 400 401--depth:: 402 This option is valid for add and update commands. Create a 'shallow' 403 clone with a history truncated to the specified number of revisions. 404 See linkgit:git-clone[1] 405 406--[no-]recommend-shallow:: 407 This option is only valid for the update command. 408 The initial clone of a submodule will use the recommended 409 `submodule.<name>.shallow` as provided by the `.gitmodules` file 410 by default. To ignore the suggestions use `--no-recommend-shallow`. 411 412-j <n>:: 413--jobs <n>:: 414 This option is only valid for the update command. 415 Clone new submodules in parallel with as many jobs. 416 Defaults to the `submodule.fetchJobs` option. 417 418<path>...:: 419 Paths to submodule(s). When specified this will restrict the command 420 to only operate on the submodules found at the specified paths. 421 (This argument is required with add). 422 423FILES 424----- 425When initializing submodules, a `.gitmodules` file in the top-level directory 426of the containing repository is used to find the url of each submodule. 427This file should be formatted in the same way as `$GIT_DIR/config`. The key 428to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] 429for details. 430 431GIT 432--- 433Part of the linkgit:git[1] suite