git submodule init and redundant data in .gitmodules/.git/config

git submodule init and redundant data in .gitmodules/.git/config

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 1534 bytes --]

Hi,

I am starting to learn submodules and hit the first state of
confusion when I encountered git-submodule init:

After git-submodule add, I find in my repository a .gitmodules file
as well as the newly-cloned submodule. I can call git-submodule
status on it to get the HEAD hash. The .gitmodules file has a stanza
for each submodule, linking remote url to local path, e.g.:

  [submodule "foo"]
    path = foo
    url = ../foo.git

The manpage then talks about git-submodule init:

    init
      Initialize the submodules, i.e. register in .git/config each
      submodule name and url found in .gitmodules. The key used in
      .git/config is submodule.$name.url. This command does not
      alter existing information in .git/config.

When I run git-submodule init, the following stanza gets added to
.git/config:

  [submodule "foo"]
    url = ../foo.git

Unless I call init, I cannot use git-submodule update.

But looking at the two stanzas, it strikes me that the remote url of
the submodule is duplicated and detached, creating redundant data
which may become desynchronised.

Why is this?

What is the reason for git-submodule init and moving the data to
.git/config?

Thanks,

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
"it is only the modern that ever becomes old-fashioned." 
                                                        -- oscar wilde
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: git submodule init and redundant data in .gitmodules/.git/config

[Sven Verdoolaege]

On Wed, Aug 15, 2007 at 06:20:05PM +0200, martin f krafft wrote:
> But looking at the two stanzas, it strikes me that the remote url of
> the submodule is duplicated and detached, creating redundant data
> which may become desynchronised.
> 
> Why is this?
> 
> What is the reason for git-submodule init and moving the data to
> .git/config?

The (most appropriate) URL from which to get updates of a submodule
may be different for different people and therefore has to be stored
in .git/config.  It was then decided that the default value
for this URL should be stored in .gitmodules.  git submodule init
simply initializes the URL using this default value.  You are free
to not call git submodule init and set a (more) appropriate URL manually.

skimo

using .gitmodule as default (was: git submodule init and redundant data in .gitmodules/.git/config)

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 2483 bytes --]

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.15.1838 +0200]:
> The (most appropriate) URL from which to get updates of a submodule
> may be different for different people and therefore has to be stored
> in .git/config.  It was then decided that the default value
> for this URL should be stored in .gitmodules.  git submodule init
> simply initializes the URL using this default value.  You are free
> to not call git submodule init and set a (more) appropriate URL manually.

Ah. I shall prepare a patch against the manpage to make this more
clear then. Thanks for your explanation.

I have one open question though: why require init? It makes perfect
sense to allow for a local override, but unless I need to override
it, git-submodule update should really just keep using the default,
which it does not as far as I can tell from my tests:

piper:/tmp/cdt.tfd29893/co/a> git submodule update
piper:/tmp/cdt.tfd29893/co/a> git-submodule init
Submodule 'b' (/tmp/cdt.tfd29893/repos/b.git) registered for path 'b'
piper:/tmp/cdt.tfd29893/co/a> git submodule update
Initialized empty Git repository in /tmp/cdt.tfd29893/co/a/b/.git/
0 blocks
Submodule path 'b': checked out '0c1403bc9e13480e70745b70f79ffb00deb25a8d'

Is there a reason for this or should I try to create a patch, which
would make git-submodule consult .gitmodules in addition to
config.submodules for all modules not found in config.submodules.

Now if I may go a step further, I'll claim that init is a misnomer,
really. Instead, I would suggest to rename it. Here are some
thoughts:

  - config
    there is already git-config, and just like git-svn reuses e.g.
    rebase, this would keep the taxonomy compact
  - cpconf
    it does copy the configuration, after all
  - override
    not sure, since it doesn't actually override anything, but sets
    it all up for the user to be able to override the config
  - instconf
    install or instantiate the configuration
  - localise
    overloaded word, but it'd be localising configuration in some
    ways
  - localconf
    hinting at making the configuration local

Comments welcome,

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
man muss noch chaos in sich haben
um einen tanzenden stern zu gebähren.
                                                -- friedrich nietzsche
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: using .gitmodule as default (was: git submodule init and redundant data in .gitmodules/.git/config)

[Josef Weidendorfer]

On Thursday 16 August 2007, martin f krafft wrote:
> also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.15.1838 +0200]:
> > The (most appropriate) URL from which to get updates of a submodule
> > may be different for different people and therefore has to be stored
> > in .git/config.  It was then decided that the default value
> > for this URL should be stored in .gitmodules.  git submodule init
> > simply initializes the URL using this default value.  You are free
> > to not call git submodule init and set a (more) appropriate URL manually.
> 
> Ah. I shall prepare a patch against the manpage to make this more
> clear then. Thanks for your explanation.
> 
> I have one open question though: why require init? It makes perfect
> sense to allow for a local override, but unless I need to override
> it, git-submodule update should really just keep using the default,

The information in .gitmodules is only a default value for the URL,
and not to be actually used. The URL in the config has to exist and
will be used for updating. So the config value is not about overriding
anything, but is required information.

The URL should not depend on the current revision you have checked out
at the moment; otherwise, if the default URL in .gitmodules changed at
some point in the history, and you check out some earlier commit in the
superproject, the update of the submodule would not work: the
submodule project still resides on the new URL, regardless of the old
information in .gitmodules at the time of the old commit.

Josef

Re: using .gitmodule as default (was: git submodule init and redundant data in .gitmodules/.git/config)

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 1154 bytes --]

also sprach Josef Weidendorfer <Josef.Weidendorfer@gmx.de> [2007.08.16.1553 +0200]:
> The information in .gitmodules is only a default value for the
> URL, and not to be actually used. The URL in the config has to
> exist and will be used for updating. So the config value is not
> about overriding anything, but is required information.

It's not required for git-submodule status.

> The URL should not depend on the current revision you have checked
> out at the moment; otherwise, if the default URL in .gitmodules
> changed at some point in the history, and you check out some
> earlier commit in the superproject, the update of the submodule
> would not work: the submodule project still resides on the new
> URL, regardless of the old information in .gitmodules at the time
> of the old commit.

Fair point. Thanks,

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
"heuristic is computer science jargon for 'doesn't actually work.'"
                                                     -- charlie reiman
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: using .gitmodule as default (was: git submodule init and redundant data in .gitmodules/.git/config)

[Josef Weidendorfer]

On Thursday 16 August 2007, martin f krafft wrote:
> also sprach Josef Weidendorfer <Josef.Weidendorfer@gmx.de> [2007.08.16.1553 +0200]:
> > The information in .gitmodules is only a default value for the
> > URL, and not to be actually used. The URL in the config has to
> > exist and will be used for updating. So the config value is not
> > about overriding anything, but is required information.
> 
> It's not required for git-submodule status.

This can show uninitialized submodules, so that's fine.

As the URL in .gitmodules is only an initial default, it probably
could be optional: if you work on a supermodule with a submodule of your own,
it is easily possible that you have no idea about what a reasonable default
of a submodule URL should be at the time you do the first supermodule
commit. It makes no sense to have to provide a bogus URL there.

Josef

[PATCH] clarify need for init in git-submodules documentation

[martin f. krafft]

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(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2c48936..b1a4f95 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -32,15 +32,17 @@ status::
 	repository. This command is the default command for git-submodule.
 
 init::
-	Initialize the submodules, i.e. register in .git/config each submodule
-	name and url found in .gitmodules. The key used in .git/config is
-	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	Initialize the submodules, i.e. register in $GIT_DIR/config each
+	submodule name and url found in .gitmodules. The key used in
+	$GIT_DIR/config is `submodule.$name.url`. This command does not alter
+	existing information in $GIT_DIR/config, it only serves to initialise
+	the local configuration from the defaults in .gitmodules.
 
 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.
+	Update the submodules registered in $GIT_DIR/config, 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.
 
 
 OPTIONS
@@ -64,9 +66,14 @@ FILES
 -----
 When initializing submodules, a .gitmodules file in the top-level directory
 of the containing repository is used to find the url of each submodule.
-This file should be formatted in the same way as $GIR_DIR/config. The key
+This file should be formatted in the same way as $GIT_DIR/config. The key
 to each submodule url is "submodule.$name.url".
 
+The file .gitmodules serves default configuration data to users who cloned the
+repository. In order to work with submodules, these data need to be copied to
+$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config
+are used for `git-submodule update`.
+
 
 AUTHOR
 ------
-- 
1.5.3.rc5.1.g44065

Re: using .gitmodule as default (was: git submodule init and redundant data in .gitmodules/.git/config)

[Lars Hjemli]

On 8/16/07, martin f krafft <madduck@madduck.net> wrote:
> I have one open question though: why require init?

The purpose of 'init' is to inform git-submodule about which
submodules you want to checkout. E.g. for a project with submodules in
directories 'a', 'b' and 'c', you could do

$ git submodule init b c
$ git submodule update

This would only fetch/checkout the submodules in direcotories 'b' and
'c', while 'git submodule status' would still inform you that there is
actually three submodules available.

Note: If you wanted to initialize all three submodules at once, you
could simply do

$ git submodule init

--
larsh

Re: [PATCH] clarify need for init in git-submodules documentation

[Sven Verdoolaege]

On Thu, Aug 16, 2007 at 08:10:02PM +0200, martin f. krafft wrote:
> +The file .gitmodules serves default configuration data to users who cloned the
> +repository. In order to work with submodules, these data need to be copied to
> +$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config
> +are used for `git-submodule update`.
> +

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.

Re: [PATCH] clarify need for init in git-submodules documentation

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 1474 bytes --]

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:
> 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.

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

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index b1a4f95..2f69047 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -71,8 +71,9 @@ to each submodule url is "submodule.$name.url".
 
 The file .gitmodules serves default configuration data to users who cloned the
 repository. In order to work with submodules, these data need to be copied to
-$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config
-are used for `git-submodule update`.
+$GIT_DIR/config with `git-submodule init`. Only the URL in $GIT_DIR/config
+is used for `git-submodule update`, as it is local information. The name/path
+relation is taken from the .gitmodules file, as it is shared data.
 
 
 AUTHOR

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
in africa some of the native tribes have a custom of beating the
ground with clubs and uttering spine chilling cries. anthropologists
call this a form of primitive self-expression. in america they call
it golf.
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] clarify need for init in git-submodules documentation

[Sven Verdoolaege]

On Fri, Aug 17, 2007 at 12:08:15PM +0200, martin f krafft wrote:
> also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:
> > 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.
> 
> If you approve of this change, I shall prepare a new patch:
> 
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index b1a4f95..2f69047 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -71,8 +71,9 @@ to each submodule url is "submodule.$name.url".
>  
>  The file .gitmodules serves default configuration data to users who cloned the

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.

>  repository. In order to work with submodules, these data need to be copied to
> -$GIT_DIR/config with `git-submodule init`. Only the data in $GIT_DIR/config
> -are used for `git-submodule update`.
> +$GIT_DIR/config with `git-submodule init`. Only the URL in $GIT_DIR/config
> +is used for `git-submodule update`, as it is local information. The name/path
> +relation is taken from the .gitmodules file, as it is shared data.

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

[PATCH] Clarify role of init command in git-submodules documentation

[martin f. krafft]

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(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2c48936..8bc818a 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -32,15 +32,17 @@ status::
 	repository. This command is the default command for git-submodule.
 
 init::
-	Initialize the submodules, i.e. register in .git/config each submodule
-	name and url found in .gitmodules. The key used in .git/config is
-	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	Initialize the submodules, i.e. register in $GIT_DIR/config each
+	submodule name and url found in .gitmodules. The key used in
+	$GIT_DIR/config is `submodule.$name.url`. This command does not alter
+	existing information in $GIT_DIR/config, it only serves to initialise
+	the local configuration from the defaults in .gitmodules.
 
 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.
+	Update the submodules registered in $GIT_DIR/config, 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.
 
 
 OPTIONS
@@ -62,10 +64,16 @@ OPTIONS
 
 FILES
 -----
-When initializing submodules, a .gitmodules file in the top-level directory
-of the containing repository is used to find the url of each submodule.
-This file should be formatted in the same way as $GIR_DIR/config. The key
-to each submodule url is "submodule.$name.url".
+To work with submodules, a user has to prepare a repository clone with the
+command `git-submodule init`. This command copies the url of each submodule
+listed in the .gitmodules file in the top-level directory of the containing
+repository to $GIT_DIR/config. The key to each submodule url is
+"submodule.$name.url".
+
+The .gitmodules file then specifies the location of each submodule with
+respect to the repository (and is shared among all contributors), while the
+url of each submodule comes from the local configuration in $GIT_DIR/config
+and can thus be modified independently of all other users.
 
 
 AUTHOR
-- 
1.5.3.rc5.40.g2f82

Re: [PATCH] Clarify role of init command in git-submodules documentation

[Sven Verdoolaege]

On Mon, Aug 20, 2007 at 09:09:44AM +0200, martin f. krafft wrote:
>  FILES
>  -----
> -When initializing submodules, a .gitmodules file in the top-level directory
> -of the containing repository is used to find the url of each submodule.
> -This file should be formatted in the same way as $GIR_DIR/config. The key
> -to each submodule url is "submodule.$name.url".
> +To work with submodules, a user has to prepare a repository clone with the

I think this is a bit ambiguous.

> +command `git-submodule init`. This command copies the url of each submodule

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

> +listed in the .gitmodules file in the top-level directory of the containing
> +repository to $GIT_DIR/config. The key to each submodule url is
> +"submodule.$name.url".
> +
> +The .gitmodules file then specifies the location of each submodule with
> +respect to the repository (and is shared among all contributors), while the
> +url of each submodule comes from the local configuration in $GIT_DIR/config
> +and can thus be modified independently of all other users.

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

Not setting M-F-T, keeping people on Cc (was: [PATCH] clarify need for init in git-submodules documentation)

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 2801 bytes --]

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.17.1131 +0200]:
> PS, please don't prune (me from) the CC list when replying.

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.

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
"for nasa, space is still a high priority." 
                                                      - george w. bush
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Clarify role of init command in git-submodules documentation

[Junio C Hamano]

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

> As per the discussion in this thread:
>
>   http://marc.info/?t=118721709500008&r=1&w=2

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.

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

Thanks.  Some comments.

> ---
> ...
>  init::
> -	Initialize the submodules, i.e. register in .git/config each submodule
> -	name and url found in .gitmodules. The key used in .git/config is
> -	`submodule.$name.url`. This command does not alter existing information
> -	in .git/config.
> +	Initialize the submodules, i.e. register in $GIT_DIR/config each
> +	submodule name and url found in .gitmodules. The key used in
> +	$GIT_DIR/config is `submodule.$name.url`. This command does not alter
> +	existing information in $GIT_DIR/config, it only serves to initialise
> +	the local configuration from the defaults in .gitmodules.

	s/initialise/initialize/;

>  FILES
>  -----
> -When initializing submodules, a .gitmodules file in the top-level directory
> -of the containing repository is used to find the url of each submodule.
> -This file should be formatted in the same way as $GIR_DIR/config. The key
> -to each submodule url is "submodule.$name.url".
> +To work with submodules, a user has to prepare a repository clone with the
> +command `git-submodule init`.

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.

> .... This command copies the url of each submodule
> +listed in the .gitmodules file in the top-level directory of the containing
> +repository to $GIT_DIR/config. The key to each submodule url is
> +"submodule.$name.url".

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

Re: [PATCH] Clarify role of init command in git-submodules documentation

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 3907 bytes --]

also sprach Junio C Hamano <gitster@pobox.com> [2007.08.20.2314 +0200]:
> > As per the discussion in this thread:
> >
> >   http://marc.info/?t=118721709500008&r=1&w=2
> 
> 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.

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.

> Is it "a user _has_ to"?  Or "a user can use 'git submodule
> init' to prepare?"
[...]
> 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:

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.

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
if loving linux is wrong, i don't want to be right.
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Clarify role of init command in git-submodules documentation

[Sven Verdoolaege]

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

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

>   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

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.

>   a submodule, the submodule's url is copied from the .gitmodules

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

>   By pulling the submodule urls out of $GIT_DIR/config,
>   git-submodule allows contributors to use different urls (e.g. via

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

Re: [PATCH] Clarify role of init command in git-submodules documentation

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 2219 bytes --]

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.21.2225 +0200]:
> >   FILES
> 
> I'm not sure this is the most appropriate name for this section.

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

> >   Users who clone the project's repository need to initialize each
> >   submodule before they can work with it. By initializing
> 
> I suppose this is implicit in the git submodule man page,

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?

> but this is only true if you actually want to use git submodule to
> work with the submodules.

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.

> >   a submodule, the submodule's url is copied from the
> >   .gitmodules
> 
> As I mentioned before, this is not strictly true. (see init::)

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

> >   By pulling the submodule urls out of $GIT_DIR/config,
> >   git-submodule allows contributors to use different urls (e.g.
> >   via
> 
> 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).

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

> Other than that, it's definitely an improvement.

Thanks,

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
"i like young girls. their stories are shorter."
                                                        -- tom mcguane
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Clarify role of init command in git-submodules documentation

[Sven Verdoolaege]

On Tue, Aug 21, 2007 at 11:03:49PM +0200, martin f krafft wrote:
> also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.21.2225 +0200]:
> > >   Users who clone the project's repository need to initialize each
> > >   submodule before they can work with it. By initializing
> > 
> > I suppose this is implicit in the git submodule man page,
> 
> It wasn't to me; that's why I am doing all this.

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

> > but this is only true if you actually want to use git submodule to
> > work with the submodules.
> 
> 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.

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

> 
> > >   a submodule, the submodule's url is copied from the
> > >   .gitmodules
> > 
> > As I mentioned before, this is not strictly true. (see init::)
> 
> You're missing something like "... unless the submodule is already
> registered, in which case it won't be overwritten", right?

Something like that, yes.

skimo

Re: [PATCH] Clarify role of init command in git-submodules documentation

[martin f krafft]

[-- Attachment #1: Type: text/plain, Size: 1480 bytes --]

also sprach Sven Verdoolaege <skimo@kotnet.org> [2007.08.22.1030 +0200]:
> > > 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.
> >
> I meant that the rest of my sentence could probably be
> implicitly understood.

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

> > 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.
> 
> Some people have been doing this manually or have homegrown
> scripts. Not that you should mention those options here.

Ok.

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

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

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
"of course the music is a great difficulty.
 you see, if one plays good music, people don't listen,
 and if one plays bad music people don't talk."
                                                        -- oscar wilde
 
spamtraps: madduck.bogus@madduck.net

[-- Attachment #2: Digital signature (see http://martin-krafft.net/gpg/) --]
[-- Type: application/pgp-signature, Size: 189 bytes --]