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