Merge branch 'jl/doc-submodule-update-checkout'

Add missing documentation for "submodule update --checkout".

* jl/doc-submodule-update-checkout:
submodule update: consistently document the '--checkout' option

diff --combined Documentation/git-submodule.txt
index 21cb59a6d6d9dd87754e2b20ec47bc67147370c7,70e09cc5583deac5b79459127a21a6bfd3898dbc..46c1eebb938dad182aeafafd9e680226c253dd65
--- 1/Documentation/git-submodule.txt
--- 2/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@@ -15,7 -15,7 +15,7 @@@ SYNOPSI
  'git submodule' [--quiet] init [--] [<path>...]
  'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
  'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-             [-f|--force] [--rebase|--merge|--checkout] [--reference <repository>]
+             [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>]
              [--depth <depth>] [--recursive] [--] [<path>...]
  'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
              [commit] [--] [<path>...]
@@@ -299,22 -299,21 +299,31 @@@ In order to ensure a current tracking b
  fetches the submodule's remote repository before calculating the
  SHA-1.  If you don't want to fetch, you should use `submodule update
  --remote --no-fetch`.
 ++
 +Use this option to integrate changes from the upstream subproject with
 +your submodule's current HEAD.  Alternatively, you can run `git pull`
 +from the submodule, which is equivalent except for the remote branch
 +name: `update --remote` uses the default upstream repository and
 +`submodule.<name>.branch`, while `git pull` uses the submodule's
 +`branch.<name>.merge`.  Prefer `submodule.<name>.branch` if you want
 +to distribute the default upstream branch with the superproject and
 +`branch.<name>.merge` if you want a more native feel while working in
 +the submodule itself.
  
  -N::
  --no-fetch::
        This option is only valid for the update command.
        Don't fetch new objects from the remote site.
  
+ --checkout::
+       This option is only valid for the update command.
+       Checkout the commit recorded in the superproject on a detached HEAD
+       in the submodule. This is the default behavior, the main use of
+       this option is to override `submodule.$name.update` when set to
+       `merge`, `rebase` or `none`.
+       If the key `submodule.$name.update` is either not explicitly set or
+       set to `checkout`, 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

diff --combined git-submodule.sh
index a33f68d27c0e1d482562373e6fd299da5dd9361a,e94b19706b2572a292a3d1cd45fbb0e19d45f59e..6135cfa9127c1da094df59236f926c01721ae58b
--- 1/git-submodule.sh
--- 2/git-submodule.sh
+++ b/git-submodule.sh
@@@ -9,7 -9,7 +9,7 @@@ USAGE="[--quiet] add [-b <branch>] [-f|
     or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]
     or: $dashless [--quiet] init [--] [<path>...]
     or: $dashless [--quiet] deinit [-f|--force] [--] <path>...
-    or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
+    or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>] [--recursive] [--] [<path>...]
     or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
     or: $dashless [--quiet] foreach [--recursive] <command>
     or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
@@@ -156,7 -156,7 +156,7 @@@ module_list(
                git ls-files -z --error-unmatch --stage -- "$@" ||
                echo "unmatched pathspec exists"
        ) |
 -      perl -e '
 +      @@PERL@@ -e '
        my %unmerged = ();
        my ($null_sha1) = ("0" x 40);
        my @out = ();
@@@ -564,12 -564,7 +564,12 @@@ cmd_foreach(
                                sm_path=$(relative_path "$sm_path") &&
                                # we make $path available to scripts ...
                                path=$sm_path &&
 -                              eval "$@" &&
 +                              if test $# -eq 1
 +                              then
 +                                      eval "$1"
 +                              else
 +                                      "$@"
 +                              fi &&
                                if test -n "$recursive"
                                then
                                        cmd_foreach "--recursive" "$@"
@@@ -740,6 -735,7 +740,6 @@@ cmd_deinit(
  cmd_update()
  {
        # parse $args after "submodule ... update".
 -      orig_flags=
        while test $# -ne 0
        do
                case "$1" in
@@@ -764,6 -760,7 +764,6 @@@
                --reference)
                        case "$2" in '') usage ;; esac
                        reference="--reference=$2"
 -                      orig_flags="$orig_flags $(git rev-parse --sq-quote "$1")"
                        shift
                        ;;
                --reference=*)
@@@ -797,6 -794,7 +797,6 @@@
                        break
                        ;;
                esac
 -              orig_flags="$orig_flags $(git rev-parse --sq-quote "$1")"
                shift
        done
  
@@@ -957,7 -955,7 +957,7 @@@ Maybe you want to use 'update --init'?"
                                prefix="$prefix$sm_path/"
                                clear_local_git_env
                                cd "$sm_path" &&
 -                              eval cmd_update "$orig_flags"
 +                              eval cmd_update
                        )
                        res=$?
                        if test $res -gt 0