Merge branch 'as/read-tree-prefix-doc-fix'
[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 Gits porcelain layer such as where to obtain the submodule via
40 the `` setting.
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 Gits 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 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.
70 The configuration of submodules
71 -------------------------------
73 Submodule operations can be configured using the following mechanisms
74 (from highest to lowest precedence):
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.
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.
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.
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.
121 -----
123 Submodules can take the following forms:
125 * The basic form described in DESCRIPTION with a Git directory,
126 a working directory, a `gitlink`, and a `.gitmodules` entry.
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.
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`.
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>/`.
163 Workflow for a third party library
164 ----------------------------------
166 # add a submodule
167 git submodule add <url> <path>
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"
174 # See the list of submodules in a superproject
175 git submodule status
177 # See FORMS on removing submodules
180 Workflow for an artificially split repo
181 --------------------------------------
183 # Enable recursion for relevant commands, such that
184 # regular commands recurse into submodules by default
185 git config --global submodule.recurse true
187 # Unlike the other commands below clone still needs
188 # its own recurse flag:
189 git clone --recurse <URL> <directory>
190 cd <directory>
192 # Get to know the code:
193 git grep foo
194 git ls-files
196 # Get new code
197 git fetch
198 git pull --rebase
200 # change worktree
201 git checkout
202 git reset
204 Implementation details
205 ----------------------
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.
216 --------
217 linkgit:git-submodule[1], linkgit:gitmodules[5].
219 GIT
220 ---
221 Part of the linkgit:git[1] suite