Merge branch 'nd/clone-case-smashing-warning'
[git.git] / Documentation / gitsubmodules.txt
blob57999e9f36686dc24e8316e91869f79b65a54960
1 gitsubmodules(7)
2 ================
4 NAME
5 ----
6 gitsubmodules - mounting one repository inside another
8 SYNOPSIS
9 --------
10  .gitmodules, $GIT_DIR/config
11 ------------------
12 git submodule
13 git <command> --recurse-submodules
14 ------------------
16 DESCRIPTION
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 `submodule.foo.path = 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 `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.
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.
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.
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).
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.
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.
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.
124 FORMS
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.
137 It is possible to construct these old form repositories manually.
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.
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`.
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.
164 To completely remove a submodule, manually delete
165 `$GIT_DIR/modules/<name>/`.
167 ACTIVE SUBMODULES
168 -----------------
170 A submodule is considered active,
172   a. if `submodule.<name>.active` is set to `true`
176   b. if the submodule's path matches the pathspec in `submodule.active`
180   c. if `submodule.<name>.url` is set.
182 and these are evaluated in this order.
184 For example:
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
195 In the above config only the submodule 'bar' and 'baz' are active,
196 'bar' due to (a) and 'baz' due to (c). 'foo' is inactive because
197 (a) takes precedence over (c)
199 Note that (c) is a historical artefact and will be ignored if the
200 (a) and (b) 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.
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
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.
225 Workflow for a third party library
226 ----------------------------------
228   # add a submodule
229   git submodule add <url> <path>
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"
236   # See the list of submodules in a superproject
237   git submodule status
239   # See FORMS on removing submodules
242 Workflow for an artificially split repo
243 --------------------------------------
245   # Enable recursion for relevant commands, such that
246   # regular commands recurse into submodules by default
247   git config --global submodule.recurse true
249   # Unlike the other commands below clone still needs
250   # its own recurse flag:
251   git clone --recurse <URL> <directory>
252   cd <directory>
254   # Get to know the code:
255   git grep foo
256   git ls-files
258   # Get new code
259   git fetch
260   git pull --rebase
262   # change worktree
263   git checkout
264   git reset
266 Implementation details
267 ----------------------
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.
277 SEE ALSO
278 --------
279 linkgit:git-submodule[1], linkgit:gitmodules[5].
283 Part of the linkgit:git[1] suite