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

[John Keeping <john@keeping.me.uk>]

On Thu, Jan 16, 2014 at 12:55:21PM -0800, W. Trevor King wrote:
> On Thu, Jan 16, 2014 at 12:21:04PM -0800, Junio C Hamano wrote:
> > "W. Trevor King" <wking@tremily.us> writes:
> > > @@ -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.

Shouldn't this also be `--checkout` (backticks), according to
CodingGuidelines.  This applies to all this options in this patch I
think.

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