On Thu, Jan 16, 2014 at 01:55:37PM -0800, Junio C Hamano wrote: > "W. Trevor King" <wk...@tremily.us> writes: > > On Thu, Jan 16, 2014 at 12:21:04PM -0800, Junio C Hamano wrote: > >> "W. Trevor King" <wk...@tremily.us> writes: > >>> +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. > >> … > >> 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? > > They are good questions that such casual readers would have, and > giving answers to them in this part of the documentation would be a > good way to give them a clear picture of how the command is designed > to be used.
How about: Note that the update command only interacts with the submodule's HEAD. It doesn't care what this head points to. If the submodule has a branch checked out, HEAD will reference that branch. If the submodule's HEAD is detached, it will reference a commit. After following any references, the commit referenced by the submodule's HEAD may resolve to the commit gitlinked by the superproject, or it may not (if you have made local submodule changes, or checked out a different superproject branch). The update command does not adjust your submodule's HEAD to point at the gitlinked commit before performing any integration. It just takes your submodle's HEAD, whatever it points to, and integrates the remote reference. 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
signature.asc
Description: OpenPGP digital signature
