patchclarify need for init in git-submodules documentation

As per the discussion in this thread:

  http://marc.info/?t=118721709500008&r=1&w=2

this patch updates the git-submodules documentation to make the situation a bit clearer.

Signed-off-by: martin f. krafft <madduck@madduck.net>
---
 Documentation/git-submodule.txt |   23 +++++++++++++++--------
 1 files changed, 15 insertions(+), 8 deletions(-)

On Thu, Aug 16, 2007 at 08:10:02PM +0200, martin f. krafft wrote:

This is not true. The url (which is local information) is taken from .git/config, the name/path relation (which is shared information) is taken from .gitmodules.

skimo

PS, please don't prune (me from) the CC list when replying.

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:

If you approve of this change, I shall prepare a new patch:

On Fri, Aug 17, 2007 at 12:08:15PM +0200, martin f krafft wrote:

This still seems to suggest that the only purpose of .gitmodules is to contain default configuration data. I think you should restrict the whole paragraph to talking about URLs. Btw, please be consistent about the spelling of URL. Either use "url" or change the "url"s in the remainder of the text to "URL". Oh, and CC Lars on your patch.

There is no mention in this man page of this relationship, so I think you should either add a description or drop the last sentence. I'm also not sure if local/shared are the best way to describe the distinction in a manual page. I was only trying to make it clear to you.

skimo

As per the discussion in this thread:

  http://marc.info/?t=118721709500008&r=1&w=2

this patch updates the git-submodules documentation to make the situation a bit clearer and documents the intended workflow.

Signed-off-by: martin f. krafft <madduck@madduck.net>
---
 Documentation/git-submodule.txt |   30 +++++++++++++++++++-----------
 1 files changed, 19 insertions(+), 11 deletions(-)

On Mon, Aug 20, 2007 at 09:09:44AM +0200, martin f. krafft wrote:

I think this is a bit ambiguous.

As you can see in the "init" section of the man pages, the url is only copied if it's not there already.

This is better than the previous version, but in my mind still a bit confusing. Let me have a go:

.gitmodules::
	This file specifies the location of each submodule with respect
	to the top-level directory of the git working tree as well as
	the default url of each submodule.  This default url is ignored
	by all git submodule subcommands, except init.  The latter can
	be used to initialize the url in $GIR_DIR/config, which is the
	url used by the other subcommands.  This file is typically
	tracked as it contains information that is shared by all
	contributors.  See also: gitlink:gitmodules[5].

$GIT_DIR/config::
	This files contains the url of each submodule in "submodule.$name.url".
	These urls are required by git submodule subcommands such as update
	and can be initialized by calling "git submodule init".
	The urls are specified in the local $GIT_DIR/config as the most
	appropriate url to get updates from may by different for different users
	and should not depend on the particular revision of the superproject
	that is currently checked out.

skimo

"martin f. krafft" <madduck@madduck.net> writes:

I'd rather see you summarize the conclusion of the thread here. Having the URL as additional supporting reference is fine, but when one reviews the "git log" output, one is not necessarily online.

Thanks.  Some comments.

	s/initialise/initialize/;

Is it "a user _has_ to"? Or "a user can use 'git submodule init' to prepare?"

Another thing that bothers me with this description is this. Imagine you are a complete "git submodule" newbie (say, myself), and want to try applying this facility to your own project (say, git.git). So I first remove git-gui from git.git repository and then try to add git-gui.git from Shawn as a submodule. Surely, I am interested in the recipe "To work with submodules" at this point, right? Does that description apply to me? Not really.

So this is not about "_has_ to" at all.  It is more like...

    You may want to work on a project you cloned from somebody
    else (we call that 'the superproject'), and find that the
    superproject has .gitmodules file at the top.  This file
    lists the subprojects that can be checked out in the
    superproject.  To make a checkout of the subprojects of the
    superproject you are interested in, you can use "git
    submodule init" to help you prime data about submodules in
    .git/config of the superproject.

I think we've seen most of that description in the above 'init::'.

I've read Sven's description on two files. My suspicion is that instead of saying there are two files involved, it may be easier to understand if we tell the story like this:

 - "git submodule" subcommands typically use data from the git
   configuration "submodule.$name.$key";

 - Definition of $name (e.g. it is just a logical token, not
   necessarily the directory name, i.e. moving a subproject to
   another directory does not have to change the $name).

 - Definition of possible $key (e.g. 'url'; others?)

 - After the initial clone of the superproject, you would not
   have any of the necessary configuration variables in _your_
   copy of the superproject.  There is a facility to help you
   prime that information.  The project gives you .gitmodules,
   and the tool gives you "git submodule init" to read from it.
   Here is what the subcommand does...

also sprach Junio C Hamano <gitster@pobox.com> [2007.08.20.2314 +0200]:

This is a good point, and I completely agree with you. In this very case, however, I *consciously* decided against a summary simply because I was hoping to capture the essence in the patch to the documentation itself. Anyway, I shall keep your suggestion in mind. Thanks for being so patient with me.

And while I still have your attention *grin*: I assume this is the correct way of going about this: keep sending updated patches to the same thread until it's accepted?

In this case, I'll just send the text before preparing the next patch; once we agree on it, I'll send a patch. That should make it easier on everyone.

[...]

Based your and Sven's suggestions, I sat down and thought for a bit, then came up with this, which I like very much:

  FILES

  A repository with submodules is identified by a .gitmodules file
  in the repository's top level (see gitlink:gitmodules[5]). This
  file specifies for each submodule its name, the url of the
  submodule's repository, as well as the location of the submodule
  within the (super)project's repository. As the .gitmodules file
  contains information shared by all users of the repository, it is
  typically tracked.

  Users who clone the project's repository need to initialize each
  submodule before they can work with it. By initializing
  a submodule, the submodule's url is copied from the .gitmodules
  file to the (local) configuration in $GIT_DIR/config. The command
  `git-submodule init` can be used for this, or the information
  manually transferred. The key to each submodule's url in
  $GIT_DIR/config is "submodule.$name.url".

  Once a submodule's url is defined in $GIT_DIR/config, the
  submodule can be cloned (from this url) into the local repository
  with `git-submodule update` at the location specified in the
  .gitmodules file.

  By pulling the submodule urls out of $GIT_DIR/config,
  git-submodule allows contributors to use different urls (e.g. via
  ssh for those with an account) and also makes submodule urls
  independent of the currently checked out revision of the
  superproject.

In the process of writing this, I also added a bit to other parts of the manpage:

  - added reference to FILES section next to .gitmodules file
    mention in description of add command, and a link to git-clone:

      ... and registered in the .gitmodules file (see section
      FILES). If no path is specified, the path is deduced from the
      repository specification (just like gitlink:git-clone[1]).

  - add to the update command description that modules can be
    specificed on the command line:

      Update all submodules registered in $GIT_DIR/config, or only
      those specified as arguments on the command line.

  - clarify what a detached HEAD is:

      This will make the submodules HEAD be detached (it then
      references a specific commit, not the tip of a branch anymore)

I am looking forward to your comments!

Thanks again for your patience.

On Tue, Aug 21, 2007 at 08:02:18PM +0200, martin f krafft wrote:

I'm not sure this is the most appropriate name for this section.

I suppose this is implicit in the git submodule man page, but this is only true if you actually want to use git submodule to work with the submodules.

As I mentioned before, this is not strictly true. (see init::)

I'm not a native speaker, but to me that sounds like you are _not_ using the urls in $GIT_DIR/config. That is, I read that as: they are pulled out of $GIT_DIR/config (and then placed somewhere else).

Other than that, it's definitely an improvement.

skimo

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.21.2225 +0200]:

I was pondering this as well. BASIC CONCEPT might be better.

It wasn't to me; that's why I am doing all this.

Anyway, when it comes to documentation, I don't think redundancy needs to be avoided as much as otherwise, don't you agree?

Is it? I tried this and after cloning a repo with submodules, it created the submodule directories alright, but it did not actually check them out/populate them, so they were empty.

You're missing something like "... unless the submodule is already registered, in which case it won't be overwritten", right?

Well, the sentence says what I wanted to say, but you're absolutely right in that it could be improved. Something like

  Since git-submodule uses the urls in $GIT_DIR/config, which is
  a local configuration file, contributers are free to use urls
  different from the default (e.g. via ssh for those with accounts).

Thanks,

On Tue, Aug 21, 2007 at 11:03:49PM +0200, martin f krafft wrote:

I meant that the rest of my sentence could probably be implicitly understood.

Some people have been doing this manually or have homegrown scripts. Not that you should mention those options here.

Something like that, yes.

skimo

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.22.1030 +0200]:

Ah. Okay, well, I'd say since this is the git-submodule manpage, we can assume that they want to work with git-submodule.

Ok.

Consider it done. Patch forthcoming, though probably not tonight, I also want to give others more time to comment.

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:

I am not used to lists where the policy is to CC posters, but seeing posts like http://marc.info/?l=git&m=113882569532399&w=2 and given my newcomer/not-(yet-)important-contributor status, I am happy to comply (and apologise for not doing so earlier).

To help others in similar positions do the right thing I am sharing my relevant mutt configuration:

  # do not set M-F-T on mails to the git mailing list
  send-hook . 'set followup_to'
  send-hook '~C git@vger\.kernel\.org' 'unset followup_to'

This takes care of not sending M-F-T in outgoing mail. The remaining issue is how to ensure that those (and only those) people end up on Cc who want to be there. I have come up with two ways: using mutt hooks and adding M-F-T to incoming mail:

  # do a <group-reply> for L when sending to the git mailing list
  # http://marc.info/?l=mutt-users&m=118734866910357&w=2
  message-hook . 'bind pager L list-reply'
  message-hook '~C git@vger\.kernel\.org' 'bind pager L group-reply'
  macro index L '<display-message>L'

This is a bit ugly, but it works. However, since it interferes with some other hooks and other parts of my configuration, I had to find another way:

the theory is that my procmail *adds* the Mail-Followup-To header to incoming git list mails that don't have it yet, and puts all From/To/Cc addresses on there. This will cause my local mutt to behave exactly like it should when I press L, but since the send-hook has disabled followup_to, my reply will *not* contain/propagate the Mail-Followup-To header.

  :0
  * ! ^Mail-Followup-To:
  * ^TO_git@vger\.kernel\.org$
  {
    CORRESPONDENTS=`formail -cxTo: -xCc: -xFrom: | tr -s '\n' ,`
    :0 fw
    |$FORMAIL -A "Mail-Followup-To: $CORRESPONDENTS"
  }

In addition, I advice to unset metoo in mutt's configuration to avoid CCing yourself on outgoing mail.

Now all I need is to filter duplicate messages with procmail in such a way that the list mail makes it through and the personal CC (which usually arrives first) is dropped:

  :0
  * ^X-Original-To: madduck@madduck\.net$
  * ^TO_git@vger\.kernel\.org$
  /dev/null

Make sure this happens *before* you weed out duplicate mail with formail.

Comments welcome, but off-list, please (Reply-To set). If important stuff turns up, I'll collect and append a summary to this thread in a bit.