submodule documentation: add options to the subcommand
When reading up on a subcommand of `git submodule <subcommand>`, it is convenient to have its options nearby and not just at the top of the man page. Add the options to each subcommand. While at it, also document the `--checkout` option for `update`. 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
eb2f2f5f6a18e7b561beb5345fb1dcb4371c7152
1 file changed
+11
-16
Documentation/git-submodule.txt
+11
-16
@@ -9,17 +9,12 @@ git-submodule - Initialize, update or inspect submodules
9
SYNOPSIS
10
--------
11
[verse]
12
-'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
13
- [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
12
+'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
13
'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
14
'git submodule' [--quiet] init [--] [<path>...]
15
'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
17
-'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
18
- [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge]
19
- [--reference <repository>] [--depth <depth>] [--recursive]
20
- [--jobs <n>] [--] [<path>...]
21
-'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
22
- [commit] [--] [<path>...]
16
+'git submodule' [--quiet] update [<options>] [--] [<path>...]
17
+'git submodule' [--quiet] summary [<options>] [--] [<path>...]
18
'git submodule' [--quiet] foreach [--recursive] <command>
19
'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
20
'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
@@ -63,7 +58,7 @@ if you choose to go that route.
58
59
COMMANDS
60
--------
66
-add::
61
+add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::
62
Add the given repository as a submodule at the given path
63
to the changeset to be committed next to the current
64
project: the current project is termed the "superproject".
@@ -104,7 +99,7 @@ together in the same relative location, and only the
99
superproject's URL needs to be provided: git-submodule will correctly
100
locate the submodule using the relative URL in .gitmodules.
101
107
-status::
102
+status [--cached] [--recursive] [--] [<path>...]::
103
Show the status of the submodules. This will print the SHA-1 of the
104
currently checked out commit for each submodule, along with the
105
submodule path and the output of 'git describe' for the
@@ -121,7 +116,7 @@ submodules with respect to the commit recorded in the index or the HEAD,
116
linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
117
too (and can also report changes to a submodule's work tree).
118
124
-init::
119
+init [--] [<path>...]::
120
Initialize the submodules recorded in the index (which were
121
added and committed elsewhere) by copying submodule
122
names and urls from .gitmodules to .git/config.
@@ -136,7 +131,7 @@ init::
131
the explicit 'init' step if you do not intend to customize
132
any submodule locations.
133
139
-deinit::
134
+deinit [-f|--force] (--all|[--] <path>...)::
135
Unregister the given submodules, i.e. remove the whole
136
`submodule.$name` section from .git/config together with their work
137
tree. Further calls to `git submodule update`, `git submodule foreach`
@@ -152,7 +147,7 @@ instead of deinit-ing everything, to prevent mistakes.
147
If `--force` is specified, the submodule's working tree will
148
be removed even if it contains local modifications.
149
155
-update::
150
+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
151
+
152
--
153
Update the registered submodules to match what the superproject
@@ -198,7 +193,7 @@ submodule with the `--init` option.
193
If `--recursive` is specified, this command will recurse into the
194
registered submodules, and update any nested submodules within.
195
--
201
-summary::
196
+summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
197
Show commit summary between the given commit (defaults to HEAD) and
198
working tree/index. For a submodule in question, a series of commits
199
in the submodule between the given super project commit and the
@@ -211,7 +206,7 @@ summary::
206
Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
207
information too.
208
214
-foreach::
209
+foreach [--recursive] <command>::
210
Evaluates an arbitrary shell command in each checked out submodule.
211
The command has access to the variables $name, $path, $sha1 and
212
$toplevel:
@@ -232,7 +227,7 @@ As an example, +git submodule foreach \'echo $path {backtick}git
227
rev-parse HEAD{backtick}'+ will show the path and currently checked out
228
commit for each submodule.
229
235
-sync::
230
+sync [--recursive] [--] [<path>...]::
231
Synchronizes submodules' remote URL configuration setting
232
to the value specified in .gitmodules. It will only affect those
233
submodules which already have a URL entry in .git/config (that is the