submodule update documentation: don't repeat ourselves
The documentation for the `git submodule update` command, repeats itself for each update option, "This is done when <option> is given, or no option is given and `submodule.<name>.update` is set to <string>. Avoid these repetitive clauses by stating the command line options take precedence over configured options. Also add 'none' to the list of options instead of mentioning it in the following running text and split the list into two parts, one that is accessible via the command line and one that is only reachable via the configuration variables. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Stefan Beller committed
Dec 27, 2016 at 15:43 UTC
fc01a5d26a8f0f80db8302d3ef3ce10924a68581
1 file changed
+14
-16
Documentation/git-submodule.txt
+14
-16
@@ -154,13 +154,13 @@ Update the registered submodules to match what the superproject
154
expects by cloning missing submodules and updating the working tree of
155
the submodules. The "updating" can be done in several ways depending
156
on command line options and the value of `submodule.<name>.update`
157
-configuration variable. Supported update procedures are:
157
+configuration variable. The command line option takes precedence over
158
+the configuration variable. if neither is given, a checkout is performed.
159
+update procedures supported both from the command line as well as setting
160
+`submodule.<name>.update`:
161
162
checkout;; the commit recorded in the superproject will be
160
- checked out in the submodule on a detached HEAD. This is
161
- done when `--checkout` option is given, or no option is
162
- given, and `submodule.<name>.update` is unset, or if it is
163
- set to 'checkout'.
163
+ checked out in the submodule on a detached HEAD.
164
+
165
If `--force` is specified, the submodule will be checked out (using
166
`git checkout --force` if appropriate), even if the commit specified
@@ -168,23 +168,21 @@ in the index of the containing repository already matches the commit
168
checked out in the submodule.
169
170
rebase;; the current branch of the submodule will be rebased
171
- onto the commit recorded in the superproject. This is done
172
- when `--rebase` option is given, or no option is given, and
173
- `submodule.<name>.update` is set to 'rebase'.
171
+ onto the commit recorded in the superproject.
172
173
merge;; the commit recorded in the superproject will be merged
176
- into the current branch in the submodule. This is done
177
- when `--merge` option is given, or no option is given, and
178
- `submodule.<name>.update` is set to 'merge'.
174
+ into the current branch in the submodule.
175
+
176
+The following procedures are only available via the `submodule.<name>.update`
177
+configuration variable:
178
179
custom command;; arbitrary shell command that takes a single
180
argument (the sha1 of the commit recorded in the
182
- superproject) is executed. This is done when no option is
183
- given, and `submodule.<name>.update` has the form of
184
- '!command'.
181
+ superproject) is executed. When `submodule.<name>.update`
182
+ is set to '!command', the remainder after the exclamation mark
183
+ is the custom command.
184
186
-When no option is given and `submodule.<name>.update` is set to 'none',
187
-the submodule is not updated.
185
+ none;; the submodule is not updated.
186
187
If the submodule is not yet initialized, and you just want to use the
188
setting as stored in .gitmodules, you can automatically initialize the