]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/gitsubmodules.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / gitsubmodules.txt
CommitLineData
d4803455
SB
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
13164169 27the submodule's working directory pointing to (i).
d4803455
SB
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
13164169 36superproject expects the submodule's working directory to be at.
d4803455
SB
37
38The section `submodule.foo.*` in the `.gitmodules` file gives additional
4f73a7f1
KS
39hints to Git's porcelain layer. For example, the `submodule.foo.url`
40setting specifies where to obtain the submodule.
d4803455
SB
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
4f73a7f1 54 overcome current limitations of Git's implementation to have
d4803455
SB
55 finer grained access:
56
4f73a7f1 57 * Size of the Git repository:
d4803455
SB
58 In its current form Git scales up poorly for large repositories containing
59 content that is not compressed by delta computation between trees.
4f73a7f1
KS
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
d4803455
SB
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.
4f73a7f1
KS
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.
d4803455
SB
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
4f73a7f1
KS
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`.
d4803455
SB
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
4f73a7f1
KS
94directory by running `status` in the submodule while paying attention
95to the `.gitignore` file of the submodule.
d4803455
SB
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.
4f73a7f1
KS
104 Git only recurses into active submodules (see "ACTIVE SUBMODULES"
105 section below).
d4803455
SB
106+
107If the submodule is not yet initialized, then the configuration
4f73a7f1 108inside the submodule does not exist yet, so where to
d4803455
SB
109obtain the submodule from is configured here for example.
110
4f73a7f1 111 * The `.gitmodules` file inside the superproject. A project usually
d4803455 112 uses this file to suggest defaults for the upstream collection
4f73a7f1
KS
113 of repositories for the mapping that is required between a
114 submodule's name and its path.
d4803455 115+
4f73a7f1
KS
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
d4803455
SB
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+
13164169 139When deinitialized or deleted (see below), the submodule's Git
d4803455
SB
140directory is automatically moved to `$GIT_DIR/modules/<name>/`
141of the superproject.
142
143 * Deinitialized submodule: A `gitlink`, and a `.gitmodules` entry,
327e524d 144but no submodule working directory. The submodule's Git directory
4f73a7f1 145may be there as after deinitializing the Git directory is kept around.
d4803455
SB
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
13164169 150the superproject's `$GIT_DIR/config` file, so the superproject's history
d4803455
SB
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+
13164169 157The deletion removes the superproject's tracking data, which are
d4803455 158both the `gitlink` entry and the section in the `.gitmodules` file.
13164169 159The submodule's working directory is removed from the file
d4803455
SB
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
4f73a7f1
KS
167ACTIVE SUBMODULES
168-----------------
169
170A submodule is considered active,
171
8e9fe16c 172 1. if `submodule.<name>.active` is set to `true`
ad471949
AH
173+
174or
175
8e9fe16c 176 2. if the submodule's path matches the pathspec in `submodule.active`
ad471949
AH
177+
178or
179
8e9fe16c 180 3. if `submodule.<name>.url` is set.
4f73a7f1
KS
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,
8e9fe16c
ES
196'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because
197(1) takes precedence over (3)
4f73a7f1 198
8e9fe16c
ES
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,
928f0ab4 201if we have a `submodule.<name>.active` set to `false` or if the
4f73a7f1
KS
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
d4803455
SB
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