[PATCH v2] submodule update: consistently document the '--checkout' option

Commit 322bb6e12f (add update 'none' flag to disable update of submodule
by default) added the '--checkout' option to "git submodule update" but
forgot to explicitly document it in synopsis, usage string and man page
(It is only mentioned implicitly in the man page). In 23d25e48 (submodule:
explicit local branch creation in module_clone) the synopsis of the man
page was updated, but the "OPTIONS" section of the man page and the usage
string of the git-submodule script still do not mention the '--checkout'
option.

Fix that by documenting this option in usage string and the "OPTIONS"
section of man page too. While at it group the update-mode options into
a single set in the usage string.

Reported-by: Matthijs Kooijman <redacted>
Signed-off-by: Jens Lehmann <redacted>
---

Am 28.02.2014 21:39, schrieb Junio C Hamano:

Jens Lehmann [off-list ref] writes:

quoted

Good point. What about this?


 Documentation/git-submodule.txt | 13 +++++++++++--
 git-submodule.sh                |  2 +-
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bfef8a0..9054217 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt

@@ -15,8 +15,8 @@ SYNOPSIS
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-	      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
-	      [--merge] [--recursive] [--] [<path>...]
+	      [-f|--force] [--checkout|--merge|--rebase] [--reference <repository>]
+	      [--depth <depth>] [--recursive] [--] [<path>...]

This has already been done by 23d25e48 (submodule: explicit local
branch creation in module_clone, 2014-01-26).  That commit also adds
some text to the description of 'update' subcommand, but not a
separate entry for '--checkout' mode.

Thanks, I missed that one.

Does the result of applying this patch except for this particular
hunk still make sense as a whole?  It appears to me that it does,
but just to double check...

Yes, it still makes sense. But I updated the commit message to
also mention 23d25e48.


 Documentation/git-submodule.txt | 9 +++++++++
 git-submodule.sh                | 2 +-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 21cb59a..dab817d 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt

@@ -315,6 +315,15 @@ the submodule itself.
 	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 --git a/git-submodule.sh b/git-submodule.sh
index a33f68d..6135cfa 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh

@@ -9,7 +9,7 @@ USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <re
    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>...]"

-- 
1.8.3.1