Documentation/gitsubmodules.txt

   1 gitsubmodules(7)
   2 ================
   3
   4 NAME
   5 ----
   6 gitsubmodules - mounting one repository inside another
   7
   8 SYNOPSIS
   9 --------
  10  .gitmodules, $GIT_DIR/config
  11 ------------------
  12 git submodule
  13 git <command> --recurse-submodules
  14 ------------------
  15
  16 DESCRIPTION
  17 -----------
  18
  19 A submodule is a repository embedded inside another repository.
  20 The submodule has its own history; the repository it is embedded
  21 in is called a superproject.
  22
  23 On the filesystem, a submodule usually (but not always - see FORMS below)
  24 consists of (i) a Git directory located under the `$GIT_DIR/modules/`
  25 directory of its superproject, (ii) a working directory inside the
  26 superproject's working directory, and a `.git` file at the root of
  27 the submodule's working directory pointing to (i).
  28
  29 Assuming the submodule has a Git directory at `$GIT_DIR/modules/foo/`
  30 and a working directory at `path/to/bar/`, the superproject tracks the
  31 submodule via a `gitlink` entry in the tree at `path/to/bar` and an entry
  32 in its `.gitmodules` file (see linkgit:gitmodules[5]) of the form
  33 `submodule.foo.path = path/to/bar`.
  34
  35 The `gitlink` entry contains the object name of the commit that the
  36 superproject expects the submodule's working directory to be at.
  37
  38 The section `submodule.foo.*` in the `.gitmodules` file gives additional
  39 hints to Git's porcelain layer. For example, the `submodule.foo.url`
  40 setting specifies where to obtain the submodule.
  41
  42 Submodules can be used for at least two different use cases:
  43
  44 1. Using another project while maintaining independent history.
  45   Submodules allow you to contain the working tree of another project
  46   within your own working tree while keeping the history of both
  47   projects separate. Also, since submodules are fixed to an arbitrary
  48   version, the other project can be independently developed without
  49   affecting the superproject, allowing the superproject project to
  50   fix itself to new versions only when desired.
  51
  52 2. Splitting a (logically single) project into multiple
  53    repositories and tying them back together. This can be used to
  54    overcome current limitations of Git's implementation to have
  55    finer grained access:
  56
  57     * Size of the Git repository:
  58       In its current form Git scales up poorly for large repositories containing
  59       content that is not compressed by delta computation between trees.
  60       For example, you can use submodules to hold large binary assets
  61       and these repositories can be shallowly cloned such that you do not
  62       have a large history locally.
  63     * Transfer size:
  64       In its current form Git requires the whole working tree present. It
  65       does not allow partial trees to be transferred in fetch or clone.
  66       If the project you work on consists of multiple repositories tied
  67       together as submodules in a superproject, you can avoid fetching the
  68       working trees of the repositories you are not interested in.
  69     * Access control:
  70       By restricting user access to submodules, this can be used to implement
  71       read/write policies for different users.
  72
  73 The configuration of submodules
  74 -------------------------------
  75
  76 Submodule operations can be configured using the following mechanisms
  77 (from highest to lowest precedence):
  78
  79  * The command line for those commands that support taking submodules
  80    as part of their pathspecs. Most commands have a boolean flag
  81    `--recurse-submodules` which specify whether to recurse into submodules.
  82    Examples are `grep` and `checkout`.
  83    Some commands take enums, such as `fetch` and `push`, where you can
  84    specify how submodules are affected.
  85
  86  * The configuration inside the submodule. This includes `$GIT_DIR/config`
  87    in the submodule, but also settings in the tree such as a `.gitattributes`
  88    or `.gitignore` files that specify behavior of commands inside the
  89    submodule.
  90 +
  91 For example an effect from the submodule's `.gitignore` file
  92 would be observed when you run `git status --ignore-submodules=none` in
  93 the superproject. This collects information from the submodule's working
  94 directory by running `status` in the submodule while paying attention
  95 to the `.gitignore` file of the submodule.
  96 +
  97 The submodule's `$GIT_DIR/config` file would come into play when running
  98 `git push --recurse-submodules=check` in the superproject, as this would
  99 check if the submodule has any changes not published to any remote. The
 100 remotes are configured in the submodule as usual in the `$GIT_DIR/config`
 101 file.
 102
 103  * The configuration file `$GIT_DIR/config` in the superproject.
 104    Git only recurses into active submodules (see "ACTIVE SUBMODULES"
 105    section below).
 106 +
 107 If the submodule is not yet initialized, then the configuration
 108 inside the submodule does not exist yet, so where to
 109 obtain the submodule from is configured here for example.
 110
 111  * The `.gitmodules` file inside the superproject. A project usually
 112    uses this file to suggest defaults for the upstream collection
 113    of repositories for the mapping that is required between a
 114    submodule's name and its path.
 115 +
 116 This file mainly serves as the mapping between the name and path of submodules
 117 in the superproject, such that the submodule's Git directory can be
 118 located.
 119 +
 120 If the submodule has never been initialized, this is the only place
 121 where submodule configuration is found. It serves as the last fallback
 122 to specify where to obtain the submodule from.
 123
 124 FORMS
 125 -----
 126
 127 Submodules can take the following forms:
 128
 129  * The basic form described in DESCRIPTION with a Git directory,
 130 a working directory, a `gitlink`, and a `.gitmodules` entry.
 131
 132  * "Old-form" submodule: A working directory with an embedded
 133 `.git` directory, and the tracking `gitlink` and `.gitmodules` entry in
 134 the superproject. This is typically found in repositories generated
 135 using older versions of Git.
 136 +
 137 It is possible to construct these old form repositories manually.
 138 +
 139 When deinitialized or deleted (see below), the submodule's Git
 140 directory is automatically moved to `$GIT_DIR/modules/<name>/`
 141 of the superproject.
 142
 143  * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
 144 but no submodule working directory. The submodule's Git directory
 145 may be there as after deinitializing the Git directory is kept around.
 146 The directory which is supposed to be the working directory is empty instead.
 147 +
 148 A submodule can be deinitialized by running `git submodule deinit`.
 149 Besides emptying the working directory, this command only modifies
 150 the superproject's `$GIT_DIR/config` file, so the superproject's history
 151 is not affected. This can be undone using `git submodule init`.
 152
 153  * Deleted submodule: A submodule can be deleted by running
 154 `git rm <submodule path> && git commit`. This can be undone
 155 using `git revert`.
 156 +
 157 The deletion removes the superproject's tracking data, which are
 158 both the `gitlink` entry and the section in the `.gitmodules` file.
 159 The submodule's working directory is removed from the file
 160 system, but the Git directory is kept around as it to make it
 161 possible to checkout past commits without requiring fetching
 162 from another repository.
 163 +
 164 To completely remove a submodule, manually delete
 165 `$GIT_DIR/modules/<name>/`.
 166
 167 ACTIVE SUBMODULES
 168 -----------------
 169
 170 A submodule is considered active,
 171
 172   1. if `submodule.<name>.active` is set to `true`
 173 +
 174 or
 175
 176   2. if the submodule's path matches the pathspec in `submodule.active`
 177 +
 178 or
 179
 180   3. if `submodule.<name>.url` is set.
 181
 182 and these are evaluated in this order.
 183
 184 For example:
 185
 186   [submodule "foo"]
 187     active = false
 188     url = https://example.org/foo
 189   [submodule "bar"]
 190     active = true
 191     url = https://example.org/bar
 192   [submodule "baz"]
 193     url = https://example.org/baz
 194
 195 In the above config only the submodule 'bar' and 'baz' are active,
 196 'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because
 197 (1) takes precedence over (3)
 198
 199 Note that (3) is a historical artefact and will be ignored if the
 200 (1) and (2) specify that the submodule is not active. In other words,
 201 if we have a `submodule.<name>.active` set to `false` or if the
 202 submodule's path is excluded in the pathspec in `submodule.active`, the
 203 url doesn't matter whether it is present or not. This is illustrated in
 204 the example that follows.
 205
 206   [submodule "foo"]
 207     active = true
 208     url = https://example.org/foo
 209   [submodule "bar"]
 210     url = https://example.org/bar
 211   [submodule "baz"]
 212     url = https://example.org/baz
 213   [submodule "bob"]
 214     ignore = true
 215   [submodule]
 216     active = b*
 217     active = :(exclude) baz
 218
 219 In here all submodules except 'baz' (foo, bar, bob) are active.
 220 'foo' due to its own active flag and all the others due to the
 221 submodule active pathspec, which specifies that any submodule
 222 starting with 'b' except 'baz' are also active, regardless of the
 223 presence of the .url field.
 224
 225 Workflow for a third party library
 226 ----------------------------------
 227
 228   # add a submodule
 229   git submodule add <url> <path>
 230
 231   # occasionally update the submodule to a new version:
 232   git -C <path> checkout <new version>
 233   git add <path>
 234   git commit -m "update submodule to new version"
 235
 236   # See the list of submodules in a superproject
 237   git submodule status
 238
 239   # See FORMS on removing submodules
 240
 241
 242 Workflow for an artificially split repo
 243 --------------------------------------
 244
 245   # Enable recursion for relevant commands, such that
 246   # regular commands recurse into submodules by default
 247   git config --global submodule.recurse true
 248
 249   # Unlike the other commands below clone still needs
 250   # its own recurse flag:
 251   git clone --recurse <URL> <directory>
 252   cd <directory>
 253
 254   # Get to know the code:
 255   git grep foo
 256   git ls-files
 257
 258   # Get new code
 259   git fetch
 260   git pull --rebase
 261
 262   # change worktree
 263   git checkout
 264   git reset
 265
 266 Implementation details
 267 ----------------------
 268
 269 When cloning or pulling a repository containing submodules the submodules
 270 will not be checked out by default; You can instruct 'clone' to recurse
 271 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 272 will maintain submodules checked out and at an appropriate revision in
 273 your working tree. Alternatively you can set 'submodule.recurse' to have
 274 'checkout' recursing into submodules.
 275
 276
 277 SEE ALSO
 278 --------
 279 linkgit:git-submodule[1], linkgit:gitmodules[5].
 280
 281 GIT
 282 ---
 283 Part of the linkgit:git[1] suite