Re: [PATCH v4 6/6] Documentation: Describe 'submodule update' modes in detail

On Thu, Jan 16, 2014 at 12:21:04PM -0800, Junio C Hamano wrote:

"W. Trevor King" [off-list ref] writes:

quoted

@@ -155,13 +155,31 @@ it contains local modifications.
 
 update::
 	Update the registered submodules, i.e. clone missing submodules and
-	checkout the commit specified in the index of the containing repository.
-	This will make the submodules HEAD be detached unless `--rebase` or
-	`--merge` is specified or the key `submodule.$name.update` is set to
-	`rebase`, `merge` or `none`. `none` can be overridden by specifying
-	`--checkout`. Setting the key `submodule.$name.update` to `!command`
-	will cause `command` to be run. `command` can be any arbitrary shell
-	command that takes a single argument, namely the sha1 to update to.
+	checkout the commit specified in the index of the containing
+	repository.  The update mode defaults to 'checkout', but be
+	configured with the 'submodule.<name>.update' setting or the
+	'--rebase', '--merge', or 'checkout' options.

Not '--checkout'?

Oops, will fix in v5.

quoted

++
+For updates that clone missing submodules, checkout-mode updates will
+create submodules with detached HEADs; all other modes will create
+submodules with a local branch named after 'submodule.<path>.branch'.
++
+For updates that do not clone missing submodules, the submodule's HEAD

That is, updates that update submodules that are already checked out?

It's submodules for which $sm_path/.git does not exist.

quoted

+is only touched when the remote reference does not match the
+submodule's HEAD (for none-mode updates, the submodule is never
+touched).  The remote reference is usually the gitlinked commit from
+the superproject's tree, but with '--remote' it is the upstream
+subproject's 'submodule.<name>.branch'.  This remote reference is
+integrated with the submodule's HEAD using the specified update mode.

I think copying some motivation from the log message of 06b1abb5
(submodule update: add --remote for submodule's upstream changes,
2012-12-19) would help the readers here.

I think a brief reference to --remote is best here, mentioning that it
has something to do with the upstream subproject.  More detail on when
you should use --remote should probably go under the docs for --remote
;).

A naïve expectation from a casual reader of the above would be "The
superproject's tree ought to point at the same commit as the tip of
the branch used in the submodule (modulo mirroring delays and
somesuch),

What is the branch used in the submodule?  The remote subproject's
current submodule.<name>.branch?  The local submodule's
submodule.<name>.branch (or localBranch) branch?  The submodule's
current HEAD?

if the repository of the superproject and submodules are maintained
properly", which would lead to "when would any sane person need to
use --remote in the first place???".

--remote is not for sane people (who will probably be pulling from
withing the submodule itself).  --remote is for folks who track too
many submodules to care about them as individuals, who just want to
blindly update to whatever the upstream subproject maintainer has in
submodule.<name>.branch.  For example, if you are a distribution with
a hundred submodules tracking all the projects you package, and want
to bump them all to a their current trunk tip in one fell swoop.

If I am reading 06b1abb5 correctly, the primary motivation behind
"--remote" seems to be that it is exactly to help the person who
wants to update superproject to satisify the "... are maintained
properly" part by fetching the latest in each of the submodules in
his superproject in preparation to 'git add .' them.  I still do not
think "--remote" was a better way than the "foreach", but that is a
separate topic.

I agree now ;), the problems with:

  $ git submodule foreach 'git pull'

are:

1. You may not be on the “right” local branch to begin with, and
2. You may not have out-of-tree submodule configs setting up the
   “right” upstream for that branch.

06b1abb did not address the former, and added a new .gitmodules-level
submodule.<name>.branch to help with the latter.  I now think all of
this would be easier if we had automatic submodule local-branch
checkouts (fixing problem 1) and synchronized out-of-tree submodule
configs (fixing problem 2).  Fixing problem 1 is all you need if you
aren't interested in sharing your out-of-tree configs.

I think 06b1abb was inspired by “we already have a way to integrate
changes in the gitlinked commit, we should reuse those to integrate
other changes”.  In hindsight, changes in the gitlinked commit are
really a checkout-time issue, while changes in other places (like the
remote subproject) are pull-time issues.  Mixing them together was
more confusing than it was worth.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy