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 Gits porcelain layer such as where to obtain the submodule via
  40 the `submodule.foo.url` setting.
  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 Gits 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       However you can also use submodules to e.g. hold large binary assets
  61       and these repositories are then 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     * Access control:
  67       By restricting user access to submodules, this can be used to implement
  68       read/write policies for different users.
  69
  70 The configuration of submodules
  71 -------------------------------
  72
  73 Submodule operations can be configured using the following mechanisms
  74 (from highest to lowest precedence):
  75
  76  * The command line for those commands that support taking submodule specs.
  77    Most commands have a boolean flag '--recurse-submodules' whether to
  78    recurse into submodules. Examples are `ls-files` or `checkout`.
  79    Some commands take enums, such as `fetch` and `push`, where you can
  80    specify how submodules are affected.
  81
  82  * The configuration inside the submodule. This includes `$GIT_DIR/config`
  83    in the submodule, but also settings in the tree such as a `.gitattributes`
  84    or `.gitignore` files that specify behavior of commands inside the
  85    submodule.
  86 +
  87 For example an effect from the submodule's `.gitignore` file
  88 would be observed when you run `git status --ignore-submodules=none` in
  89 the superproject. This collects information from the submodule's working
  90 directory by running `status` in the submodule, which does pay attention
  91 to its `.gitignore` file.
  92 +
  93 The submodule's `$GIT_DIR/config` file would come into play when running
  94 `git push --recurse-submodules=check` in the superproject, as this would
  95 check if the submodule has any changes not published to any remote. The
  96 remotes are configured in the submodule as usual in the `$GIT_DIR/config`
  97 file.
  98
  99  * The configuration file `$GIT_DIR/config` in the superproject.
 100    Typical configuration at this place is controlling if a submodule
 101    is recursed into at all via the `active` flag for example.
 102 +
 103 If the submodule is not yet initialized, then the configuration
 104 inside the submodule does not exist yet, so configuration where to
 105 obtain the submodule from is configured here for example.
 106
 107  * the `.gitmodules` file inside the superproject. Additionally to the
 108    required mapping between submodule's name and path, a project usually
 109    uses this file to suggest defaults for the upstream collection
 110    of repositories.
 111 +
 112 This file mainly serves as the mapping between name and path in
 113 the superproject, such that the submodule's git directory can be
 114 located.
 115 +
 116 If the submodule has never been initialized, this is the only place
 117 where submodule configuration is found. It serves as the last fallback
 118 to specify where to obtain the submodule from.
 119
 120 FORMS
 121 -----
 122
 123 Submodules can take the following forms:
 124
 125  * The basic form described in DESCRIPTION with a Git directory,
 126 a working directory, a `gitlink`, and a `.gitmodules` entry.
 127
 128  * "Old-form" submodule: A working directory with an embedded
 129 `.git` directory, and the tracking `gitlink` and `.gitmodules` entry in
 130 the superproject. This is typically found in repositories generated
 131 using older versions of Git.
 132 +
 133 It is possible to construct these old form repositories manually.
 134 +
 135 When deinitialized or deleted (see below), the submodule’s Git
 136 directory is automatically moved to `$GIT_DIR/modules/<name>/`
 137 of the superproject.
 138
 139  * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
 140 but no submodule working directory. The submodule’s git directory
 141 may be there as after deinitializing the git directory is kept around.
 142 The directory which is supposed to be the working directory is empty instead.
 143 +
 144 A submodule can be deinitialized by running `git submodule deinit`.
 145 Besides emptying the working directory, this command only modifies
 146 the superproject’s `$GIT_DIR/config` file, so the superproject’s history
 147 is not affected. This can be undone using `git submodule init`.
 148
 149  * Deleted submodule: A submodule can be deleted by running
 150 `git rm <submodule path> && git commit`. This can be undone
 151 using `git revert`.
 152 +
 153 The deletion removes the superproject’s tracking data, which are
 154 both the `gitlink` entry and the section in the `.gitmodules` file.
 155 The submodule’s working directory is removed from the file
 156 system, but the Git directory is kept around as it to make it
 157 possible to checkout past commits without requiring fetching
 158 from another repository.
 159 +
 160 To completely remove a submodule, manually delete
 161 `$GIT_DIR/modules/<name>/`.
 162
 163 Workflow for a third party library
 164 ----------------------------------
 165
 166   # add a submodule
 167   git submodule add <url> <path>
 168
 169   # occasionally update the submodule to a new version:
 170   git -C <path> checkout <new version>
 171   git add <path>
 172   git commit -m "update submodule to new version"
 173
 174   # See the list of submodules in a superproject
 175   git submodule status
 176
 177   # See FORMS on removing submodules
 178
 179
 180 Workflow for an artificially split repo
 181 --------------------------------------
 182
 183   # Enable recursion for relevant commands, such that
 184   # regular commands recurse into submodules by default
 185   git config --global submodule.recurse true
 186
 187   # Unlike the other commands below clone still needs
 188   # its own recurse flag:
 189   git clone --recurse <URL> <directory>
 190   cd <directory>
 191
 192   # Get to know the code:
 193   git grep foo
 194   git ls-files
 195
 196   # Get new code
 197   git fetch
 198   git pull --rebase
 199
 200   # change worktree
 201   git checkout
 202   git reset
 203
 204 Implementation details
 205 ----------------------
 206
 207 When cloning or pulling a repository containing submodules the submodules
 208 will not be checked out by default; You can instruct 'clone' to recurse
 209 into submodules. The 'init' and 'update' subcommands of 'git submodule'
 210 will maintain submodules checked out and at an appropriate revision in
 211 your working tree. Alternatively you can set 'submodule.recurse' to have
 212 'checkout' recursing into submodules.
 213
 214
 215 SEE ALSO
 216 --------
 217 linkgit:git-submodule[1], linkgit:gitmodules[5].
 218
 219 GIT
 220 ---
 221 Part of the linkgit:git[1] suite