Doc/gitsubmodules: make some changes to improve readability and syntax
* Only mention porcelain commands in examples * Split a sentence for better readability * Add missing apostrophes * Clearly specify the advantages of using submodules * Avoid abbreviations * Use "Git" consistently * Improve readability of certain lines * Clarify when a submodule is considered active Helped-by: Eric Sunshine <sunshine@sunshineco.com> Helped-by: Stefan Beller <sbeller@google.com> Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kaartic Sivaraam committed
Jan 14, 2018 at 23:07 UTC
4f73a7f1245d9210da8515798b5a8e68b3b8069c
1 file changed
+79
-21
Documentation/gitsubmodules.txt
+79
-21
@@ -36,8 +36,8 @@ 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.
39
+hints to Git's porcelain layer. For example, the `submodule.foo.url`
40
+setting specifies where to obtain the submodule.
41
42
Submodules can be used for at least two different use cases:
43
@@ -51,18 +51,21 @@ Submodules can be used for at least two different use cases:
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
54
+ overcome current limitations of Git's implementation to have
55
finer grained access:
56
57
- * Size of the git repository:
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
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,9 +76,10 @@ The configuration of submodules
76
Submodule operations can be configured using the following mechanisms
77
(from highest to lowest precedence):
78
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
+ * 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.
85
@@ -87,8 +91,8 @@ Submodule operations can be configured using the following mechanisms
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
90
-directory by running `status` in the submodule, which does pay attention
91
-to its `.gitignore` file.
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
@@ -97,20 +101,20 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`
101
file.
102
103
* 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.
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
104
-inside the submodule does not exist yet, so configuration where to
108
+inside the submodule does not exist yet, so where to
109
obtain the submodule from is configured here for example.
110
107
- * the `.gitmodules` file inside the superproject. Additionally to the
108
- required mapping between submodule's name and path, a project usually
111
+ * The `.gitmodules` file inside the superproject. A project usually
112
uses this file to suggest defaults for the upstream collection
110
- of repositories.
113
+ of repositories for the mapping that is required between a
114
+ submodule's name and its path.
115
+
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
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
@@ -137,8 +141,8 @@ directory is automatically moved to `$GIT_DIR/modules/<name>/`
141
of the superproject.
142
143
* 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.
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`.
@@ -160,6 +164,60 @@ from another repository.
164
To completely remove a submodule, manually delete
165
`$GIT_DIR/modules/<name>/`.
166
167
+ACTIVE SUBMODULES
168
+-----------------
169
+
170
+A submodule is considered active,
171
+
172
+ (a) if `submodule.<name>.active` is set to `true`
173
+ or
174
+ (b) if the submodule's path matches the pathspec in `submodule.active`
175
+ or
176
+ (c) if `submodule.<name>.url` is set.
177
+
178
+and these are evaluated in this order.
179
+
180
+For example:
181
+
182
+ [submodule "foo"]
183
+ active = false
184
+ url = https://example.org/foo
185
+ [submodule "bar"]
186
+ active = true
187
+ url = https://example.org/bar
188
+ [submodule "baz"]
189
+ url = https://example.org/baz
190
+
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)
194
+
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 `submodule.active`, the
199
+url doesn't matter whether it is present or not. This is illustrated in
200
+the example that follows.
201
+
202
+ [submodule "foo"]
203
+ active = true
204
+ url = https://example.org/foo
205
+ [submodule "bar"]
206
+ url = https://example.org/bar
207
+ [submodule "baz"]
208
+ url = https://example.org/baz
209
+ [submodule "bob"]
210
+ ignore = true
211
+ [submodule]
212
+ active = b*
213
+ active = :(exclude) baz
214
+
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.
220
+
221
Workflow for a third party library
222
----------------------------------
223