Documentation/submodule: add command references and update options
Reference the "git diff" and "git status" commands where they learned functionality that in earlier git versions was only available through the 'summary' and 'status' subcommands of "git submodule". The short option '-n' for '--summary-limit' was missing from the synopsis and the --init option was missing from the "options" section, add those there. And while at it, quote all options in backticks so they are decorated properly in the output formats which support that. Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jens Lehmann committed
Aug 1, 2011 at 22:49 UTC
402e8a6d9af392536c10f749275588ded78bca31
1 file changed
+26
-12
Documentation/git-submodule.txt
+26
-12
@@ -15,7 +15,8 @@ SYNOPSIS
15
'git submodule' [--quiet] init [--] [<path>...]
16
'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
17
[--reference <repository>] [--merge] [--recursive] [--] [<path>...]
18
-'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
18
+'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
19
+ [commit] [--] [<path>...]
20
'git submodule' [--quiet] foreach [--recursive] <command>
21
'git submodule' [--quiet] sync [--] [<path>...]
22
@@ -106,8 +107,13 @@ status::
107
repository and `U` if the submodule has merge conflicts.
108
This command is the default command for 'git submodule'.
109
+
109
-If '--recursive' is specified, this command will recurse into nested
110
+If `--recursive` is specified, this command will recurse into nested
111
submodules, and show their status as well.
112
++
113
+If you are only interested in changes of the currently initialized
114
+submodules with respect to the commit recorded in the index or the HEAD,
115
+linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
116
+too (and can also report changes to a submodule's work tree).
117
118
init::
119
Initialize the submodules, i.e. register each submodule name
@@ -123,26 +129,29 @@ init::
129
update::
130
Update the registered submodules, i.e. clone missing submodules and
131
checkout the commit specified in the index of the containing repository.
126
- This will make the submodules HEAD be detached unless '--rebase' or
127
- '--merge' is specified or the key `submodule.$name.update` is set to
132
+ This will make the submodules HEAD be detached unless `--rebase` or
133
+ `--merge` is specified or the key `submodule.$name.update` is set to
134
`rebase` or `merge`.
135
+
136
If the submodule is not yet initialized, and you just want to use the
137
setting as stored in .gitmodules, you can automatically initialize the
132
-submodule with the --init option.
138
+submodule with the `--init` option.
139
+
134
-If '--recursive' is specified, this command will recurse into the
140
+If `--recursive` is specified, this command will recurse into the
141
registered submodules, and update any nested submodules within.
142
143
summary::
144
Show commit summary between the given commit (defaults to HEAD) and
145
working tree/index. For a submodule in question, a series of commits
146
in the submodule between the given super project commit and the
141
- index or working tree (switched by --cached) are shown. If the option
142
- --files is given, show the series of commits in the submodule between
147
+ index or working tree (switched by `--cached`) are shown. If the option
148
+ `--files` is given, show the series of commits in the submodule between
149
the index of the super project and the working tree of the submodule
144
- (this option doesn't allow to use the --cached option or to provide an
150
+ (this option doesn't allow to use the `--cached` option or to provide an
151
explicit commit).
152
++
153
+Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
154
+information too.
155
156
foreach::
157
Evaluates an arbitrary shell command in each checked out submodule.
@@ -153,9 +162,9 @@ foreach::
162
superproject, $sha1 is the commit as recorded in the superproject,
163
and $toplevel is the absolute path to the top-level of the superproject.
164
Any submodules defined in the superproject but not checked out are
156
- ignored by this command. Unless given --quiet, foreach prints the name
165
+ ignored by this command. Unless given `--quiet`, foreach prints the name
166
of each submodule before evaluating the command.
158
- If --recursive is given, submodules are traversed recursively (i.e.
167
+ If `--recursive` is given, submodules are traversed recursively (i.e.
168
the given shell command is evaluated in nested submodules as well).
169
A non-zero return from the command in any submodule causes
170
the processing to terminate. This can be overridden by adding '|| :'
@@ -233,13 +242,18 @@ OPTIONS
242
If the key `submodule.$name.update` is set to `rebase`, this option is
243
implicit.
244
245
+--init::
246
+ This option is only valid for the update command.
247
+ Initialize all submodules for which "git submodule init" has not been
248
+ called so far before updating.
249
+
250
--reference <repository>::
251
This option is only valid for add and update commands. These
252
commands sometimes need to clone a remote repository. In this case,
253
this option will be passed to the linkgit:git-clone[1] command.
254
+
255
*NOTE*: Do *not* use this option unless you have read the note
242
-for linkgit:git-clone[1]'s --reference and --shared options carefully.
256
+for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
257
258
--recursive::
259
This option is only valid for foreach, update and status commands.