Documentation / gitsubmodules.txton commit wt-status.h: drop stdio.h include (7a06fb0)
   1gitsubmodules(7)
   2================
   3
   4NAME
   5----
   6gitsubmodules - mounting one repository inside another
   7
   8SYNOPSIS
   9--------
  10 .gitmodules, $GIT_DIR/config
  11------------------
  12git submodule
  13git <command> --recurse-submodules
  14------------------
  15
  16DESCRIPTION
  17-----------
  18
  19A submodule is a repository embedded inside another repository.
  20The submodule has its own history; the repository it is embedded
  21in is called a superproject.
  22
  23On the filesystem, a submodule usually (but not always - see FORMS below)
  24consists of (i) a Git directory located under the `$GIT_DIR/modules/`
  25directory of its superproject, (ii) a working directory inside the
  26superproject's working directory, and a `.git` file at the root of
  27the submodule's working directory pointing to (i).
  28
  29Assuming the submodule has a Git directory at `$GIT_DIR/modules/foo/`
  30and a working directory at `path/to/bar/`, the superproject tracks the
  31submodule via a `gitlink` entry in the tree at `path/to/bar` and an entry
  32in its `.gitmodules` file (see linkgit:gitmodules[5]) of the form
  33`submodule.foo.path = path/to/bar`.
  34
  35The `gitlink` entry contains the object name of the commit that the
  36superproject expects the submodule's working directory to be at.
  37
  38The section `submodule.foo.*` in the `.gitmodules` file gives additional
  39hints to Git's porcelain layer. For example, the `submodule.foo.url`
  40setting specifies where to obtain the submodule.
  41
  42Submodules can be used for at least two different use cases:
  43
  441. 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
  522. 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
  73The configuration of submodules
  74-------------------------------
  75
  76Submodule 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+
  91For example an effect from the submodule's `.gitignore` file
  92would be observed when you run `git status --ignore-submodules=none` in
  93the superproject. This collects information from the submodule's working
  94directory by running `status` in the submodule while paying attention
  95to the `.gitignore` file of the submodule.
  96+
  97The submodule's `$GIT_DIR/config` file would come into play when running
  98`git push --recurse-submodules=check` in the superproject, as this would
  99check if the submodule has any changes not published to any remote. The
 100remotes are configured in the submodule as usual in the `$GIT_DIR/config`
 101file.
 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+
 107If the submodule is not yet initialized, then the configuration
 108inside the submodule does not exist yet, so where to
 109obtain 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+
 116This file mainly serves as the mapping between the name and path of submodules
 117in the superproject, such that the submodule's Git directory can be
 118located.
 119+
 120If the submodule has never been initialized, this is the only place
 121where submodule configuration is found. It serves as the last fallback
 122to specify where to obtain the submodule from.
 123
 124FORMS
 125-----
 126
 127Submodules can take the following forms:
 128
 129 * The basic form described in DESCRIPTION with a Git directory,
 130a 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
 134the superproject. This is typically found in repositories generated
 135using older versions of Git.
 136+
 137It is possible to construct these old form repositories manually.
 138+
 139When deinitialized or deleted (see below), the submodule's Git
 140directory is automatically moved to `$GIT_DIR/modules/<name>/`
 141of the superproject.
 142
 143 * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
 144but no submodule working directory. The submodule's Git directory
 145may be there as after deinitializing the Git directory is kept around.
 146The directory which is supposed to be the working directory is empty instead.
 147+
 148A submodule can be deinitialized by running `git submodule deinit`.
 149Besides emptying the working directory, this command only modifies
 150the superproject's `$GIT_DIR/config` file, so the superproject's history
 151is 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
 155using `git revert`.
 156+
 157The deletion removes the superproject's tracking data, which are
 158both the `gitlink` entry and the section in the `.gitmodules` file.
 159The submodule's working directory is removed from the file
 160system, but the Git directory is kept around as it to make it
 161possible to checkout past commits without requiring fetching
 162from another repository.
 163+
 164To completely remove a submodule, manually delete
 165`$GIT_DIR/modules/<name>/`.
 166
 167ACTIVE SUBMODULES
 168-----------------
 169
 170A submodule is considered active,
 171
 172  1. if `submodule.<name>.active` is set to `true`
 173+
 174or
 175
 176  2. if the submodule's path matches the pathspec in `submodule.active`
 177+
 178or
 179
 180  3. if `submodule.<name>.url` is set.
 181
 182and these are evaluated in this order.
 183
 184For 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
 195In 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
 199Note 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,
 201if we have a `submodule.<name>.active` set to `false` or if the
 202submodule's path is excluded in the pathspec in `submodule.active`, the
 203url doesn't matter whether it is present or not. This is illustrated in
 204the 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
 219In 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
 221submodule active pathspec, which specifies that any submodule
 222starting with 'b' except 'baz' are also active, regardless of the
 223presence of the .url field.
 224
 225Workflow 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
 242Workflow 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
 266Implementation details
 267----------------------
 268
 269When cloning or pulling a repository containing submodules the submodules
 270will not be checked out by default; You can instruct 'clone' to recurse
 271into submodules. The 'init' and 'update' subcommands of 'git submodule'
 272will maintain submodules checked out and at an appropriate revision in
 273your working tree. Alternatively you can set 'submodule.recurse' to have
 274'checkout' recursing into submodules.
 275
 276
 277SEE ALSO
 278--------
 279linkgit:git-submodule[1], linkgit:gitmodules[5].
 280
 281GIT
 282---
 283Part of the linkgit:git[1] suite