On Thu, Jan 16, 2014 at 12:21:04PM -0800, Junio C Hamano wrote: > "W. Trevor King" <wking@xxxxxxxxxx> 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. > > ++ > > +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
Attachment:
signature.asc
Description: OpenPGP digital signature