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>

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 918bd1d1bd062ae16c00509a1ac1051714f9ca51..0105bdbe1c9da3c0057b6d6ed5aa1ed69099e225 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,17 +9,12 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
 SYNOPSIS
 --------
 [verse]

-'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
-             [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
+'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]

 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)

-'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-             [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge]
-             [--reference <repository>] [--depth <depth>] [--recursive]
-             [--jobs <n>] [--] [<path>...]
-'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
-             [commit] [--] [<path>...]
+'git submodule' [--quiet] update [<options>] [--] [<path>...]
+'git submodule' [--quiet] summary [<options>] [--] [<path>...]

 'git submodule' [--quiet] foreach [--recursive] <command>
 'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
 'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
 'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
 'git submodule' [--quiet] absorbgitdirs [--] [<path>...]


@@ -63,7 +58,7 @@ if you choose to go that route.
 
 COMMANDS
 --------
 
 COMMANDS
 --------

-add::
+add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::

        Add the given repository as a submodule at the given path
        to the changeset to be committed next to the current
        project: the current project is termed the "superproject".
        Add the given repository as a submodule at the given path
        to the changeset to be committed next to the current
        project: the current project is termed the "superproject".


@@ -104,7 +99,7 @@ together in the same relative location, and only the
 superproject's URL needs to be provided: git-submodule will correctly
 locate the submodule using the relative URL in .gitmodules.
 
 superproject's URL needs to be provided: git-submodule will correctly
 locate the submodule using the relative URL in .gitmodules.
 

-status::
+status [--cached] [--recursive] [--] [<path>...]::

        Show the status of the submodules. This will print the SHA-1 of the
        currently checked out commit for each submodule, along with the
        submodule path and the output of 'git describe' for the
        Show the status of the submodules. This will print the SHA-1 of the
        currently checked out commit for each submodule, along with the
        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,
 linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
 too (and can also report changes to a submodule's work tree).
 
 linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
 too (and can also report changes to a submodule's work tree).
 

-init::
+init [--] [<path>...]::

        Initialize the submodules recorded in the index (which were
        added and committed elsewhere) by copying submodule
        names and urls from .gitmodules to .git/config.
        Initialize the submodules recorded in the index (which were
        added and committed elsewhere) by copying submodule
        names and urls from .gitmodules to .git/config.


@@ -136,7 +131,7 @@ init::
        the explicit 'init' step if you do not intend to customize
        any submodule locations.
 
        the explicit 'init' step if you do not intend to customize
        any submodule locations.
 

-deinit::
+deinit [-f|--force] (--all|[--] <path>...)::

        Unregister the given submodules, i.e. remove the whole
        `submodule.$name` section from .git/config together with their work
        tree. Further calls to `git submodule update`, `git submodule foreach`
        Unregister the given submodules, i.e. remove the whole
        `submodule.$name` section from .git/config together with their work
        tree. Further calls to `git submodule update`, `git submodule foreach`


@@ -152,7 +147,7 @@ instead of deinit-ing everything, to prevent mistakes.
 If `--force` is specified, the submodule's working tree will
 be removed even if it contains local modifications.
 
 If `--force` is specified, the submodule's working tree will
 be removed even if it contains local modifications.
 

-update::
+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::

 +
 --
 Update the registered submodules to match what the superproject
 +
 --
 Update the registered submodules to match what the superproject


@@ -198,7 +193,7 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --

-summary::
+summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::

        Show commit summary between the given commit (defaults to HEAD) and
        working tree/index. For a submodule in question, a series of commits
        in the submodule between the given super project commit and the
        Show commit summary between the given commit (defaults to HEAD) and
        working tree/index. For a submodule in question, a series of commits
        in the submodule between the given super project commit and the


@@ -211,7 +206,7 @@ summary::
 Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
 information too.
 
 Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
 information too.
 

-foreach::
+foreach [--recursive] <command>::

        Evaluates an arbitrary shell command in each checked out submodule.
        The command has access to the variables $name, $path, $sha1 and
        $toplevel:
        Evaluates an arbitrary shell command in each checked out submodule.
        The command has access to the variables $name, $path, $sha1 and
        $toplevel:


@@ -232,7 +227,7 @@ As an example, +git submodule foreach \'echo $path {backtick}git
 rev-parse HEAD{backtick}'+ will show the path and currently checked out
 commit for each submodule.
 
 rev-parse HEAD{backtick}'+ will show the path and currently checked out
 commit for each submodule.
 

-sync::
+sync [--recursive] [--] [<path>...]::

        Synchronizes submodules' remote URL configuration setting
        to the value specified in .gitmodules. It will only affect those
        submodules which already have a URL entry in .git/config (that is the
        Synchronizes submodules' remote URL configuration setting
        to the value specified in .gitmodules. It will only affect those
        submodules which already have a URL entry in .git/config (that is the