Merge branch 'ms/non-ascii-ticks'
[git/git.git] / Documentation / gitsubmodules.txt
1 gitsubmodules(7)
2 ================
5 ----
6 gitsubmodules - mounting one repository inside another
9 --------
10 .gitmodules, $GIT_DIR/config
11 ------------------
12 git submodule
13 git <command> --recurse-submodules
14 ------------------
17 -----------
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.
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).
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 ` = path/to/bar`.
35 The `gitlink` entry contains the object name of the commit that the
36 superproject expects the submodule's working directory to be at.
38 The section `*` in the `.gitmodules` file gives additional
39 hints to Git's porcelain layer. For example, the ``
40 setting specifies where to obtain the submodule.
42 Submodules can be used for at least two different use cases:
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.
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:
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.
73 The configuration of submodules
74 -------------------------------
76 Submodule operations can be configured using the following mechanisms
77 (from highest to lowest precedence):
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.
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.
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.
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.
125 -----
127 Submodules can take the following forms:
129 * The basic form described in DESCRIPTION with a Git directory,
130 a working directory, a `gitlink`, and a `.gitmodules` entry.
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.
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`.
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>/`.
168 -----------------
170 A submodule is considered active,
172 (a) if `submodule.<name>.active` is set to `true`
173 or
174 (b) if the submodule's path matches the pathspec in ``
175 or
176 (c) if `submodule.<name>.url` is set.
178 and these are evaluated in this order.
180 For example:
182 [submodule "foo"]
183 active = false
184 url =
185 [submodule "bar"]
186 active = true
187 url =
188 [submodule "baz"]
189 url =
191 In the above config only the submodule 'bar' and 'baz' are active,
192 'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because
193 (a) takes precedence over (c)
195 Note that (c) is a historical artefact and will be ignored if the
196 (a) and (b) specify that the submodule is not active. In other words,
197 if we have an `submodule.<name>.active` set to `false` or if the
198 submodule's path is excluded in the pathspec in ``, the
199 url doesn't matter whether it is present or not. This is illustrated in
200 the example that follows.
202 [submodule "foo"]
203 active = true
204 url =
205 [submodule "bar"]
206 url =
207 [submodule "baz"]
208 url =
209 [submodule "bob"]
210 ignore = true
211 [submodule]
212 active = b*
213 active = :(exclude) baz
215 In here all submodules except 'baz' (foo, bar, bob) are active.
216 'foo' due to its own active flag and all the others due to the
217 submodule active pathspec, which specifies that any submodule
218 starting with 'b' except 'baz' are also active, regardless of the
219 presence of the .url field.
221 Workflow for a third party library
222 ----------------------------------
224 # add a submodule
225 git submodule add <url> <path>
227 # occasionally update the submodule to a new version:
228 git -C <path> checkout <new version>
229 git add <path>
230 git commit -m "update submodule to new version"
232 # See the list of submodules in a superproject
233 git submodule status
235 # See FORMS on removing submodules
238 Workflow for an artificially split repo
239 --------------------------------------
241 # Enable recursion for relevant commands, such that
242 # regular commands recurse into submodules by default
243 git config --global submodule.recurse true
245 # Unlike the other commands below clone still needs
246 # its own recurse flag:
247 git clone --recurse <URL> <directory>
248 cd <directory>
250 # Get to know the code:
251 git grep foo
252 git ls-files
254 # Get new code
255 git fetch
256 git pull --rebase
258 # change worktree
259 git checkout
260 git reset
262 Implementation details
263 ----------------------
265 When cloning or pulling a repository containing submodules the submodules
266 will not be checked out by default; You can instruct 'clone' to recurse
267 into submodules. The 'init' and 'update' subcommands of 'git submodule'
268 will maintain submodules checked out and at an appropriate revision in
269 your working tree. Alternatively you can set 'submodule.recurse' to have
270 'checkout' recursing into submodules.
274 --------
275 linkgit:git-submodule[1], linkgit:gitmodules[5].
277 GIT
278 ---
279 Part of the linkgit:git[1] suite