From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 14 Mar 2014 21:26:58 +0000 (-0700)
Subject: Merge branch 'jl/doc-submodule-update-checkout'
X-Git-Tag: v2.0.0-rc0~112
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/d73e6160031e1753c81cf0d72b0f9525cf93dca0?hp=-c

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
---

d73e6160031e1753c81cf0d72b0f9525cf93dca0
diff --combined Documentation/git-submodule.txt
index 21cb59a6d6,70e09cc558..46c1eebb93
--- a/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 a33f68d27c,e94b19706b..6135cfa912
--- a/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