git submodule foreach: Provide access to submodule name, as '$name'

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2289d11f0e350886296bf961a9acb2e9b6f0ffd9..97c32fe264aa5f4f8abbf5361fa509a2ccbff48a 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,11 +9,13 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
+'git submodule' [--quiet] add [-b branch]
+             [--reference <repository>] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--] [<path>...]
-'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
+             [--reference <repository>] [--merge] [--] [<path>...]
+'git submodule' [--quiet] summary [--cached] [--summary-limit <n>] [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach <command>
 'git submodule' [--quiet] sync [--] [<path>...]
 
@@ -129,7 +131,8 @@ summary::
 
 foreach::
        Evaluates an arbitrary shell command in each checked out submodule.
-       The command has access to the variables $path and $sha1:
+       The command has access to the variables $name, $path and $sha1:
+       $name is the name of the relevant submodule section in .gitmodules,
        $path is the name of the submodule directory relative to the
        superproject, and $sha1 is the commit as recorded in the superproject.
        Any submodules defined in the superproject but not checked out are
@@ -139,8 +142,9 @@ foreach::
        the processing to terminate. This can be overridden by adding '|| :'
        to the end of the command.
 +
-As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will
-show the path and currently checked out commit for each submodule.
+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.
 
 sync::
        Synchronizes submodules' remote URL configuration setting
@@ -179,15 +183,6 @@ OPTIONS
        This option is only valid for the update command.
        Don't fetch new objects from the remote site.
 
---rebase::
-       This option is only valid for the update command.
-       Rebase the current branch onto the commit recorded in the
-       superproject. If this option is given, the submodule's HEAD will not
-       be detached. If a a merge failure prevents this process, you will have
-       to resolve these failures with linkgit:git-rebase[1].
-       If the key `submodule.$name.update` is set to `rebase`, this option is
-       implicit.
-
 --merge::
        This option is only valid for the update command.
        Merge the commit recorded in the superproject into the current branch
@@ -198,6 +193,23 @@ OPTIONS
        If the key `submodule.$name.update` is set to `merge`, this option is
        implicit.
 
+--rebase::
+       This option is only valid for the update command.
+       Rebase the current branch onto the commit recorded in the
+       superproject. If this option is given, the submodule's HEAD will not
+       be detached. If a a merge failure prevents this process, you will have
+       to resolve these failures with linkgit:git-rebase[1].
+       If the key `submodule.$name.update` is set to `rebase`, this option is
+       implicit.
+
+--reference <repository>::
+       This option is only valid for add and update commands.  These
+       commands sometimes need to clone a remote repository. In this case,
+       this option will be passed to the linkgit:git-clone[1] command.
++
+*NOTE*: Do *not* use this option unless you have read the note
+for linkgit:git-clone[1]'s --reference and --shared options carefully.
+
 <path>...::
        Paths to submodule(s). When specified this will restrict the command
        to only operate on the submodules found at the specified paths.