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

On Thu, Jan 16, 2014 at 01:55:37PM -0800, Junio C Hamano wrote:

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

quoted

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

quoted

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

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.

…
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