threads / patch / 8535

patch, 3 partsAdd gitmodules(5)

Subject: [PATCH 2/3] Add gitmodules(5)

## tl;dr

29 messages between Jun 9, 2007 and Jun 13, 2007. Diffs are folded; open one to read it.

replies: 28people: 6as markdown or json

Lars Hjemli· Jun 9, 2007, 21:38 UTC · lore

[PATCH 0/3] submodule improvements

This is a series of somewhat unrelated changes, but all related to git-submodule.

1/3 implements a mapping between submodule path and submodule name 2/3 adds a gitmodules(5) document 3/3 fixes a bug in testscript t7400, noticed when making 1/3

The stats:

Documentation/Makefile | 2 +- Documentation/git-submodule.txt | 16 +++-- Documentation/gitmodules.txt | 63 ++++++++++++++++++++ git-submodule.sh | 44 +++++++++---- t/t7400-submodule-basic.sh | 2 +- ...submodule-basic.sh => t7401-submodule-named.sh} | 27 ++++++--- 6 files changed, 124 insertions(+), 30 deletions(-)

Lars Hjemli· Jun 9, 2007, 21:38 UTC · re: Lars Hjemli · lore

[PATCH 1/3] git-submodule: allow submodule name and path to differ

This teaches git-submodule to check module.*.path when looking for the config for a submodule path. If no match is found it falls back to the current behaviour (module.$path).

With this change a submodule can be checked out at different paths in different revisions of the superproject without changing the submodule properties in .git/config.

While at it, add a new testscript for named submodules. This is basically the same tests as can be found in t7400, but modified for a submodule with name != path.

Signed-off-by: Lars Hjemli <hjemli@gmail.com>
---
 Documentation/git-submodule.txt                    |   16 ++++---
 git-submodule.sh                                   |   44 +++++++++++++------
 ...submodule-basic.sh => t7401-submodule-named.sh} |   27 ++++++++----
 3 files changed, 59 insertions(+), 28 deletions(-)
 copy t/{t7400-submodule-basic.sh => t7401-submodule-named.sh} (82%)
Show changes to 4 files +59 −28

Documentation/git-submodule.txt, git-submodule.sh, t/t7400-submodule-basic.sh, t/t7401-submodule-named.sh

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index f8fb80f..176e16d 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -24,8 +24,8 @@ status::
 
 init::
 	Initialize the submodules, i.e. register in .git/config each submodule
-	path and url found in .gitmodules. The key used in git/config is
-	`submodule.$path.url`. This command does not alter existing information
+	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.
 
 update::
@@ -50,11 +50,15 @@ 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 "module.$path.url".
+The .gitmodules file in the top-level directory of the containing repository
+is used to map submodule path to submodule name. The map consist of keys
+named `module.$name.path` with a value matching the path found in the index of
+the containing repository. If no such key is found for a specific path, the
+submodule path is used as submodule name.
 
+During `git-submodule init` the url for each submodule is registered in
+.git/config of the containing repository. The url is located under the key
+`module.$name.url` in .gitmodules.
 
 AUTHOR
 ------
diff --git a/git-submodule.sh b/git-submodule.sh
index 8bdd99a..d9f0c91 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -25,6 +25,18 @@ say()
 	fi
 }
 
+#
+# Resolve submodule name from path, use path as name if no mapping exist
+#
+# $1 = path
+#
+module_name()
+{
+	name=$(GIT_CONFIG=.gitmodules git-config --get-regexp '^module\..*\.path$' "$1" |
+		sed -nre 's/^module\.(.+)\.path .+$/\1/p')
+	test -z "$name" && name="$1"
+	echo $name
+}
 
 #
 # Clone a submodule
@@ -62,18 +74,19 @@ modules_init()
 	git ls-files --stage -- "$@" | grep -e '^160000 ' |
 	while read mode sha1 stage path
 	do
-		# Skip already registered paths
-		url=$(git-config submodule."$path".url)
+		# Skip already registered submodules
+		name=$(module_name "$path")
+		url=$(git-config submodule."$name".url)
 		test -z "$url" || continue
 
-		url=$(GIT_CONFIG=.gitmodules git-config module."$path".url)
+		url=$(GIT_CONFIG=.gitmodules git-config module."$name".url)
 		test -z "$url" &&
-		die "No url found for submodule '$path' in .gitmodules"
+		die "No url found for submodule '$name', path '$path' in .gitmodules"
 
-		git-config submodule."$path".url "$url" ||
-		die "Failed to register url for submodule '$path'"
+		git-config submodule."$name".url "$url" ||
+		die "Failed to register url for submodule '$name', path '$path'"
 
-		say "Submodule '$path' registered with url '$url'"
+		say "Submodule '$name', path '$path' registered with url '$url'"
 	done
 }
 
@@ -87,13 +100,14 @@ modules_update()
 	git ls-files --stage -- "$@" | grep -e '^160000 ' |
 	while read mode sha1 stage path
 	do
-		url=$(git-config submodule."$path".url)
+		name=$(module_name "$path")
+		url=$(git-config submodule."$name".url)
 		if test -z "$url"
 		then
 			# Only mention uninitialized submodules when its
 			# path have been specified
 			test "$#" != "0" &&
-			say "Submodule '$path' not initialized"
+			say "Submodule '$name', path '$path' not initialized"
 			continue
 		fi
 
@@ -104,15 +118,15 @@ modules_update()
 
 		subsha1=$(unset GIT_DIR && cd "$path" &&
 			git-rev-parse --verify HEAD) ||
-		die "Unable to find current revision of submodule '$path'"
+		die "Unable to find current revision of submodule '$name', path '$path'"
 
 		if test "$subsha1" != "$sha1"
 		then
 			(unset GIT_DIR && cd "$path" && git-fetch &&
 				git-checkout -q "$sha1") ||
-			die "Unable to checkout '$sha1' in submodule '$path'"
+			die "Unable to checkout '$sha1' in submodule '$name', path '$path'"
 
-			say "Submodule '$path': checked out '$sha1'"
+			say "Submodule '$name', path '$path': checked out '$sha1'"
 		fi
 	done
 }
@@ -132,10 +146,12 @@ modules_list()
 	git ls-files --stage -- "$@" | grep -e '^160000 ' |
 	while read mode sha1 stage path
 	do
-		if ! test -d "$path"/.git
+		name=$(module_name "$path")
+		url=$(git-config submodule."$name".url)
+		if test -z "$url" || ! test -d "$path"/.git
 		then
 			say "-$sha1 $path"
-			continue;
+			continue
 		fi
 		revname=$(unset GIT_DIR && cd "$path" && git-describe $sha1)
 		if git diff-files --quiet -- "$path"
diff --git a/t/t7400-submodule-basic.sh b/t/t7401-submodule-named.sh
similarity index 82%
copy from t/t7400-submodule-basic.sh
copy to t/t7401-submodule-named.sh
index 3940433..3c3d195 100755
--- a/t/t7400-submodule-basic.sh
+++ b/t/t7401-submodule-named.sh
@@ -3,10 +3,10 @@
 # Copyright (c) 2007 Lars Hjemli
 #
 
-test_description='Basic porcelain support for submodules
+test_description='Basic porcelain support for named submodules
 
 This test tries to verify basic sanity of the init, update and status
-subcommands of git-submodule.
+subcommands of git-submodule when a submodule name differs from its path.
 '
 
 . ./test-lib.sh
@@ -18,7 +18,7 @@ subcommands of git-submodule.
 #  -add directory lib to 'superproject', this creates a DIRLINK entry
 #  -add a couple of regular files to enable testing of submodule filtering
 #  -mv lib subrepo
-#  -add an entry to .gitmodules for path 'lib'
+#  -add an entry to .gitmodules for submodule 'foo'
 #
 test_expect_success 'Prepare submodule testing' '
 	mkdir lib &&
@@ -40,7 +40,7 @@ test_expect_success 'Prepare submodule testing' '
 	git-add a lib z &&
 	git-commit -m "super commit 1" &&
 	mv lib .subrepo &&
-	GIT_CONFIG=.gitmodules git-config module.lib.url git://example.com/lib.git
+	GIT_CONFIG=.gitmodules git-config module.foo.url git://example.com/libfoo.git
 '
 
 test_expect_success 'status should only print one line' '
@@ -52,14 +52,25 @@ test_expect_success 'status should initially be "missing"' '
 	git-submodule status | grep "^-$rev1"
 '
 
+test_expect_success 'init should fail when map from path to name is missing' '
+	if git-submodule init
+	then
+		echo "[OOPS] init should have failed"
+		false
+	elif ! GIT_CONFIG=.gitmodules git-config module.foo.path lib
+	then
+		echo "[OOPS] init failed but so did git-config"
+	fi
+'
+
 test_expect_success 'init should register submodule url in .git/config' '
 	git-submodule init &&
-	url=$(git-config submodule.lib.url) &&
-	if test "$url" != "git://example.com/lib.git"
+	url=$(git-config submodule.foo.url) &&
+	if test "$url" != "git://example.com/libfoo.git"
 	then
 		echo "[OOPS] init succeeded but submodule url is wrong"
 		false
-	elif ! git-config submodule.lib.url ./.subrepo
+	elif ! git-config submodule.foo.url ./.subrepo
 	then
 		echo "[OOPS] init succeeded but update of url failed"
 		false
@@ -72,7 +83,7 @@ test_expect_success 'update should fail when path is used by a file' '
 	then
 		echo "[OOPS] update should have failed"
 		false
-	elif test -f lib && test "$(cat lib)" != "hello"
+	elif test "$(cat lib)" != "hello"
 	then
 		echo "[OOPS] update failed but lib file was molested"
 		false

-- 
1.5.2.1.914.gbd3a7
Junio C Hamano· Jun 10, 2007, 00:27 UTC · re: Lars Hjemli · lore

Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ

Lars Hjemli <hjemli@gmail.com> writes:
> This teaches git-submodule to check module.*.path when looking for the
> config for a submodule path. If no match is found it falls back to the
> current behaviour (module.$path).

I have a feeling that it might be much less troublesome in the longer term to admit that module.$path was a mistake and support only one format; wouldn't trying to support both leave ambiguity and confusion?

Johannes Schindelin· Jun 10, 2007, 07:25 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ

Hi,
On Sat, 9 Jun 2007, Junio C Hamano wrote:
Show 9 quoted lines
> Lars Hjemli <hjemli@gmail.com> writes:
> 
> > This teaches git-submodule to check module.*.path when looking for the 
> > config for a submodule path. If no match is found it falls back to the 
> > current behaviour (module.$path).
> 
> I have a feeling that it might be much less troublesome in the longer 
> term to admit that module.$path was a mistake and support only one 
> format; wouldn't trying to support both leave ambiguity and confusion?

Just my 2cents: git-submodule is not yet in any released version. So let's fix things early. In our world, it's not like you lose face when you have to admit mistakes. (Instead, you lose face when you refuse to fix them.) Ah, if only politics learnt from our world...

Ciao, Dscho

Junio C Hamano· Jun 10, 2007, 08:23 UTC · re: Johannes Schindelin · lore

Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
Show 16 quoted lines
> On Sat, 9 Jun 2007, Junio C Hamano wrote:
>
>> Lars Hjemli <hjemli@gmail.com> writes:
>> 
>> > This teaches git-submodule to check module.*.path when looking for the 
>> > config for a submodule path. If no match is found it falls back to the 
>> > current behaviour (module.$path).
>> 
>> I have a feeling that it might be much less troublesome in the longer 
>> term to admit that module.$path was a mistake and support only one 
>> format; wouldn't trying to support both leave ambiguity and confusion?
>
> Just my 2cents: git-submodule is not yet in any released version. So let's 
> fix things early. In our world, it's not like you lose face when you have 
> to admit mistakes. (Instead, you lose face when you refuse to fix them.) 
> Ah, if only politics learnt from our world...

Well, I completely agree with what you said up to "So let's fix things early.", but when I re-read what I wrote, I realize that my wording was bad --- I did not mean to drive the discussion in that direction.

It was not Lars's *mistake* to admit to begin with. His was one valid design that was consistent within his patch series. The thing is that there just was a better alternative suggested later; it does not make the first iteration a mistake in any way.

So, Lars, my apologies if I offended you -- I did not mean it that way.

Lars Hjemli· Jun 10, 2007, 08:42 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ

On 6/10/07, Junio C Hamano <gitster@pobox.com> wrote:
Show 32 quoted lines
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
> > On Sat, 9 Jun 2007, Junio C Hamano wrote:
> >
> >> Lars Hjemli <hjemli@gmail.com> writes:
> >>
> >> > This teaches git-submodule to check module.*.path when looking for the
> >> > config for a submodule path. If no match is found it falls back to the
> >> > current behaviour (module.$path).
> >>
> >> I have a feeling that it might be much less troublesome in the longer
> >> term to admit that module.$path was a mistake and support only one
> >> format; wouldn't trying to support both leave ambiguity and confusion?
> >
> > Just my 2cents: git-submodule is not yet in any released version. So let's
> > fix things early. In our world, it's not like you lose face when you have
> > to admit mistakes. (Instead, you lose face when you refuse to fix them.)
> > Ah, if only politics learnt from our world...
>
> Well, I completely agree with what you said up to "So let's fix
> things early.", but when I re-read what I wrote, I realize that
> my wording was bad --- I did not mean to drive the discussion in
> that direction.
>
> It was not Lars's *mistake* to admit to begin with.  His was one
> valid design that was consistent within his patch series.  The
> thing is that there just was a better alternative suggested
> later; it does not make the first iteration a mistake in any
> way.
>
> So, Lars, my apologies if I offended you -- I did not mean it
> that way.
No need for apologies, no offence taken :)
-- 
larsh
Lars Hjemli· Jun 10, 2007, 08:37 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ

On 6/10/07, Junio C Hamano <gitster@pobox.com> wrote:
Show 9 quoted lines
> Lars Hjemli <hjemli@gmail.com> writes:
>
> > This teaches git-submodule to check module.*.path when looking for the
> > config for a submodule path. If no match is found it falls back to the
> > current behaviour (module.$path).
>
> I have a feeling that it might be much less troublesome in the
> longer term to admit that module.$path was a mistake and support
> only one format;
Hmm, what the patch does should match what is described in
  http://article.gmane.org/gmane.comp.version-control.git/48879

except that I've kept [module] instead of renaming it to [submodule]. But my wording ("module.$path") might be disconcerting :)

Fwiw: I do admit that the [path "path"] construct was a mistake.
-- 
larsh
Lars Hjemli· Jun 9, 2007, 21:38 UTC · re: Lars Hjemli · lore
This adds documentation for the .gitmodules file.
Signed-off-by: Lars Hjemli <hjemli@gmail.com>
---
 Documentation/Makefile       |    2 +-
 Documentation/gitmodules.txt |   63 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/gitmodules.txt
Show changes to 2 files +64 −1

Documentation/Makefile, Documentation/gitmodules.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9cef480..2ad18e0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -2,7 +2,7 @@ MAN1_TXT= \
 	$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
 		$(wildcard git-*.txt)) \
 	gitk.txt
-MAN5_TXT=gitattributes.txt gitignore.txt
+MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt
 MAN7_TXT=git.txt
 
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
new file mode 100644
index 0000000..37888c9
--- /dev/null
+++ b/Documentation/gitmodules.txt
@@ -0,0 +1,63 @@
+gitmodules(5)
+=============
+
+NAME
+----
+gitmodules - defining submodule properties
+
+SYNOPSIS
+--------
+.gitmodules
+
+
+DESCRIPTION
+-----------
+
+The `.gitmodules` file, located in the top-level directory of a
+gitlink:git[7] working tree, is a text file with a layout matching the
+requirements of gitlink:git-config[1].
+
+The file consists of sections named `module`, divided into one subsection
+per submodule. The subsections are named with the logical name of the
+submodule it describes.
+
+Each submodule can contain the following keys.
+
+module.$name.path::
+	Define a path, relative to the top-level directory of the git
+	working tree, where the submodule is expected to be checked out.
+
+module.$name.url::
+	Define a url from where the submodule repository can be cloned.
+
+
+EXAMPLES
+--------
+
+Consider the following .gitmodules file:
+
+	[module 'libfoo']
+		path = include/foo
+		url = git://example1.com/git/libfoo.git
+
+	[module 'libbar']
+		url = git://example2.com/pub/git/libbar.git
+
+
+This defines two submodules, `libfoo` and `libbar`. The former specifies
+both a checkout path and a suggested url, while the latter only specifies
+a url. This file would make gitlink:git-submodule[1] map the path
+`include/foo` to the submodule `libfoo` and the path `libbar` to the
+submodule `libbar`.
+
+SEE ALSO
+--------
+gitlink:git-submodule[1] gitlink:git-config[1]
+
+DOCUMENTATION
+-------------
+Documentation by Lars Hjemli <hjemli@gmail.com>
+
+GIT
+---
+Part of the gitlink:git[7] suite

-- 
1.5.2.1.914.gbd3a7
Frank Lichtenheld· Jun 10, 2007, 00:28 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

The unofficial git documentation nitpicker at work ;)
On Sat, Jun 09, 2007 at 11:38:51PM +0200, Lars Hjemli wrote:
> +The `.gitmodules` file, located in the top-level directory of a
> +gitlink:git[7] working tree, is a text file with a layout matching the

That link seems superfluous to me. I would have used "syntax" instead of "layout".

Show 5 quoted lines
> +requirements of gitlink:git-config[1].
> +
> +The file consists of sections named `module`, divided into one subsection
> +per submodule. The subsections are named with the logical name of the
> +submodule it describes.

"sections named module" sounds confusing to me. Why are there multiple sections named module? (for the record: I know what you mean, I just don't know if it couldn't be said simpler) Maybe better "subsections of section `module`, one per submodule"? Hmm, sounds ugly too.

Show 8 quoted lines
> +Each submodule can contain the following keys.
> +
> +module.$name.path::
> +	Define a path, relative to the top-level directory of the git
> +	working tree, where the submodule is expected to be checked out.
> +
> +module.$name.url::
> +	Define a url from where the submodule repository can be cloned.
For .path a "Defaults to name of submodule" probably wouldn't hurt.

For the sake of documentation consistency I would suggest module.<name>.path. You can compare the output of $ grep "\.<[a-z]" Documentation/*.txt with $ grep "\.\$[a-z]" Documentation/*.txt to see what I mean.

Show 6 quoted lines
> +	[module 'libfoo']
> +		path = include/foo
> +		url = git://example1.com/git/libfoo.git
> +
> +	[module 'libbar']
> +		url = git://example2.com/pub/git/libbar.git

This would actually be a syntax error in a git config file (subsection names can be enclosed in "" but not '').

Gruesse,
-- 
Frank Lichtenheld <frank@lichtenheld.de>
www: http://www.djpig.de/
Lars Hjemli· Jun 10, 2007, 08:58 UTC · re: Frank Lichtenheld · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/10/07, Frank Lichtenheld <frank@lichtenheld.de> wrote:
> The unofficial git documentation nitpicker at work ;)
That's good, keep it up :)
Show 6 quoted lines
>
> On Sat, Jun 09, 2007 at 11:38:51PM +0200, Lars Hjemli wrote:
> > +The `.gitmodules` file, located in the top-level directory of a
> > +gitlink:git[7] working tree, is a text file with a layout matching the
>
> That link seems superfluous to me.

Yeah, what I really wanted here was a link to the definition of "git working tree". I'll drop it.

> I would have used "syntax" instead of "layout".
Agreed
Show 12 quoted lines
>
> > +requirements of gitlink:git-config[1].
> > +
> > +The file consists of sections named `module`, divided into one subsection
> > +per submodule. The subsections are named with the logical name of the
> > +submodule it describes.
>
> "sections named module" sounds confusing to me. Why are there multiple
> sections named module? (for the record: I know what you mean, I just
> don't know if it couldn't be said simpler)
> Maybe better "subsections of section `module`, one per submodule"?
> Hmm, sounds ugly too.
Good documentation is hard, so I'll work on it some more...
Show 11 quoted lines
>
> > +Each submodule can contain the following keys.
> > +
> > +module.$name.path::
> > +     Define a path, relative to the top-level directory of the git
> > +     working tree, where the submodule is expected to be checked out.
> > +
> > +module.$name.url::
> > +     Define a url from where the submodule repository can be cloned.
>
> For .path a "Defaults to name of submodule" probably wouldn't hurt.

True. But there might be some issues with this rule, so I'll leave it as is for now.

Show 7 quoted lines
>
> For the sake of documentation consistency I would suggest
> module.<name>.path. You can compare the output of
> $ grep "\.<[a-z]" Documentation/*.txt
> with
> $ grep "\.\$[a-z]" Documentation/*.txt
> to see what I mean.
That was very descriptive, thanks!
Show 10 quoted lines
>
> > +     [module 'libfoo']
> > +             path = include/foo
> > +             url = git://example1.com/git/libfoo.git
> > +
> > +     [module 'libbar']
> > +             url = git://example2.com/pub/git/libbar.git
>
> This would actually be a syntax error in a git config file
> (subsection names can be enclosed in "" but not '').
Shame on me for drinking while documenting ;-)
Thanks for the review, I'll try to send a fixed-up patch later today.

-- larsh

Johannes Schindelin· Jun 10, 2007, 09:48 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

Hi,
On Sun, 10 Jun 2007, Lars Hjemli wrote:
> Shame on me for drinking while documenting ;-)

So I'm not the only one trying to cheer me up with some ethanol-containing beverage, when writing documentation?

Ciao, Dscho

Lars Hjemli· Jun 10, 2007, 10:10 UTC · re: Johannes Schindelin · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/10/07, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
Show 9 quoted lines
> Hi,
>
> On Sun, 10 Jun 2007, Lars Hjemli wrote:
>
> > Shame on me for drinking while documenting ;-)
>
> So I'm not the only one trying to cheer me up with some ethanol-containing
> beverage, when writing documentation?
>

Nope, you're not alone. Certain activities do require lots of stimuli (also known as "Gourmet Stout" :)

-- 
larsh
Sven Verdoolaege· Jun 10, 2007, 12:12 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

On Sun, Jun 10, 2007 at 10:58:29AM +0200, Lars Hjemli wrote:
Show 14 quoted lines
> On 6/10/07, Frank Lichtenheld <frank@lichtenheld.de> wrote:
> >> +Each submodule can contain the following keys.
> >> +
> >> +module.$name.path::
> >> +     Define a path, relative to the top-level directory of the git
> >> +     working tree, where the submodule is expected to be checked out.
> >> +
> >> +module.$name.url::
> >> +     Define a url from where the submodule repository can be cloned.
> >
> >For .path a "Defaults to name of submodule" probably wouldn't hurt.
> 
> True. But there might be some issues with this rule, so I'll leave it
> as is for now.
And what might those issues be?
How about adding something like
	For a given path relative to the top-level directory of the
	git working tree, the logical name of the submodule at that
	path (if any) is the submodule <name> with a module.<name>.path
	value equal to that path, or, if no such submodule exists, the
	submodule <path>.  It is an error for different submodules to have
	identical path values.

For uniformity, you may also want to specify that a path value must (or must not) end with a slash.

Other than that, I like it. It doesn't have the extensions proposed by Linus, but it seems to be forward compatible with them.

skimo
Lars Hjemli· Jun 10, 2007, 12:30 UTC · re: Sven Verdoolaege · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/10/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
Show 17 quoted lines
> On Sun, Jun 10, 2007 at 10:58:29AM +0200, Lars Hjemli wrote:
> > On 6/10/07, Frank Lichtenheld <frank@lichtenheld.de> wrote:
> > >> +Each submodule can contain the following keys.
> > >> +
> > >> +module.$name.path::
> > >> +     Define a path, relative to the top-level directory of the git
> > >> +     working tree, where the submodule is expected to be checked out.
> > >> +
> > >> +module.$name.url::
> > >> +     Define a url from where the submodule repository can be cloned.
> > >
> > >For .path a "Defaults to name of submodule" probably wouldn't hurt.
> >
> > True. But there might be some issues with this rule, so I'll leave it
> > as is for now.
>
> And what might those issues be?
There's been some discussion about allowing a default value for path, see
  http://comments.gmane.org/gmane.comp.version-control.git/49620
Show 12 quoted lines
>
> How about adding something like
>
>         For a given path relative to the top-level directory of the
>         git working tree, the logical name of the submodule at that
>         path (if any) is the submodule <name> with a module.<name>.path
>         value equal to that path, or, if no such submodule exists, the
>         submodule <path>.  It is an error for different submodules to have
>         identical path values.
>
> For uniformity, you may also want to specify that a path value
> must (or must not) end with a slash.
Nice suggestions, I'll try to come up with a new patch later today
> Other than that, I like it.
Thanks :)
> It doesn't have the extensions proposed by Linus, but it seems
> to be forward compatible with them.

I'm trying to take baby-steps with the submodule support, so the module/submodule extension Linus talked about would possibly come at a later stage.

Hmm, maybe I should just rename [module] to [submodule] right now? It would be better forward compatible with the proposed extension, it would 'harmonize' the section names used in .gitmodules and .git/config, and it would offer a clean break from what's currently supported in 'master'.

-- larsh

Sven Verdoolaege· Jun 10, 2007, 12:40 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

On Sun, Jun 10, 2007 at 02:30:58PM +0200, Lars Hjemli wrote:
Show 11 quoted lines
> On 6/10/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
> >On Sun, Jun 10, 2007 at 10:58:29AM +0200, Lars Hjemli wrote:
> >> >For .path a "Defaults to name of submodule" probably wouldn't hurt.
> >>
> >> True. But there might be some issues with this rule, so I'll leave it
> >> as is for now.
> >
> >And what might those issues be?
> 
> There's been some discussion about allowing a default value for path, see
>  http://comments.gmane.org/gmane.comp.version-control.git/49620

Euhm... this just points back to this thread... or are you referring to Junio's misinterpretation of the patch 1/3 commit message?

Show 8 quoted lines
> >It doesn't have the extensions proposed by Linus, but it seems
> >to be forward compatible with them.
> 
> I'm trying to take baby-steps with the submodule support, so the
> module/submodule extension Linus talked about would possibly come at a
> later stage.
> 
> Hmm, maybe I should just rename [module] to [submodule] right now?

I don't see the need, but if you _really_ can't resist then please do it sooner rather than later.

skimo
Lars Hjemli· Jun 10, 2007, 12:51 UTC · re: Sven Verdoolaege · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/10/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
Show 14 quoted lines
> On Sun, Jun 10, 2007 at 02:30:58PM +0200, Lars Hjemli wrote:
> > On 6/10/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
> > >On Sun, Jun 10, 2007 at 10:58:29AM +0200, Lars Hjemli wrote:
> > >> >For .path a "Defaults to name of submodule" probably wouldn't hurt.
> > >>
> > >> True. But there might be some issues with this rule, so I'll leave it
> > >> as is for now.
> > >
> > >And what might those issues be?
> >
> > There's been some discussion about allowing a default value for path, see
> >  http://comments.gmane.org/gmane.comp.version-control.git/49620
>
> Euhm... this just points back to this thread...
I know ;-)
> or are you referring to Junio's misinterpretation of the patch 1/3
> commit message?

Well, yes, I _think_ it's a misinterpretation but there is always the possibility of me being exceptionally slow and not getting his point.

Show 12 quoted lines
>
> > >It doesn't have the extensions proposed by Linus, but it seems
> > >to be forward compatible with them.
> >
> > I'm trying to take baby-steps with the submodule support, so the
> > module/submodule extension Linus talked about would possibly come at a
> > later stage.
> >
> > Hmm, maybe I should just rename [module] to [submodule] right now?
>
> I don't see the need, but if you _really_ can't resist then please do it
> sooner rather than later.
Ok

-- larsh

Junio C Hamano· Jun 10, 2007, 20:57 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

"Lars Hjemli" <hjemli@gmail.com> writes:
Show 5 quoted lines
> Hmm, maybe I should just rename [module] to [submodule] right now? It
> would be better forward compatible with the proposed extension, it
> would 'harmonize' the section names used in .gitmodules and
> .git/config, and it would offer a clean break from what's currently
> supported in 'master'.

Yes, the difference between '[submodule]' vs '[module]' in .git/config and .gitmodules confused me while looking at your latest patch series. I am in favor of unifying them. We would not be breaking any released version if we harmonize them now.

Lars Hjemli· Jun 10, 2007, 21:14 UTC · re: Junio C Hamano · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/10/07, Junio C Hamano <gitster@pobox.com> wrote:
Show 13 quoted lines
> "Lars Hjemli" <hjemli@gmail.com> writes:
>
> > Hmm, maybe I should just rename [module] to [submodule] right now? It
> > would be better forward compatible with the proposed extension, it
> > would 'harmonize' the section names used in .gitmodules and
> > .git/config, and it would offer a clean break from what's currently
> > supported in 'master'.
>
> Yes, the difference between '[submodule]' vs '[module]' in
> .git/config and .gitmodules confused me while looking at your
> latest patch series.  I am in favor of unifying them.  We would
> not be breaking any released version if we harmonize them now.
>

Good, then I'll do it that way. And I'll drop the "unless otherwise noted, name=path" behaviour. If we later decide it would be useful we can always "re-add" it.

-- larsh

Sven Verdoolaege· Jun 11, 2007, 08:34 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

On Sun, Jun 10, 2007 at 11:14:27PM +0200, Lars Hjemli wrote:
> And I'll drop the "unless otherwise
> noted, name=path" behaviour. If we later decide it would be useful we
> can always "re-add" it.

So every (sub)module subsection will have to have a path element? Why?

skimo
Lars Hjemli· Jun 11, 2007, 10:47 UTC · re: Sven Verdoolaege · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/11/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
Show 6 quoted lines
> On Sun, Jun 10, 2007 at 11:14:27PM +0200, Lars Hjemli wrote:
> > And I'll drop the "unless otherwise
> > noted, name=path" behaviour. If we later decide it would be useful we
> > can always "re-add" it.
>
> So every (sub)module subsection will have to have a path element?
Yes
> Why?

It addresses Junio's concern about ambiguity and confusion. And it felt like the 'safe choice', i.e. starting out with a strict rule and possibly loosen it later on is a lot easier than starting loose and then trying to make it stricter.

Btw: adding support for the optional path specification on top of my
latest patch-series is trivial:
Show changes to git-submodule.sh +1 −3
diff --git a/git-submodule.sh b/git-submodule.sh
index 89a3885..297272b 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -34,8 +34,7 @@ module_name()
 {
        name=$(GIT_CONFIG=.gitmodules git-config --get-regexp
'^submodule\..*\.path$' "$1" |
        sed -nre 's/^submodule\.(.+)\.path .+$/\1/p')
-       test -z "$name" &&
-       die "No submodule mapping found in .gitmodules for path '$path'"
+       test -z "$name" && name="$path"
        echo "$name"
 }

--
larsh
Sven Verdoolaege· Jun 11, 2007, 11:04 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

On Mon, Jun 11, 2007 at 12:47:43PM +0200, Lars Hjemli wrote:
Show 13 quoted lines
> On 6/11/07, Sven Verdoolaege <skimo@kotnet.org> wrote:
> >On Sun, Jun 10, 2007 at 11:14:27PM +0200, Lars Hjemli wrote:
> >> And I'll drop the "unless otherwise
> >> noted, name=path" behaviour. If we later decide it would be useful we
> >> can always "re-add" it.
> >
> >So every (sub)module subsection will have to have a path element?
> 
> Yes
> 
> >Why?
> 
> It addresses Junio's concern about ambiguity and confusion.
Junio, is this really what you meant?

Linus even advocated removing the mapping completely (http://article.gmane.org/gmane.comp.version-control.git/48871), but I wouldn't go that far.

skimo
Junio C Hamano· Jun 11, 2007, 16:17 UTC · re: Sven Verdoolaege · lore

Re: [PATCH 2/3] Add gitmodules(5)

Sven Verdoolaege <skimo@kotnet.org> writes:
Show 5 quoted lines
>> >Why?
>> 
>> It addresses Junio's concern about ambiguity and confusion.
>
> Junio, is this really what you meant?

I think I initially misread Lars's patch and log message that said:

    This teaches git-submodule to check module.*.path when looking for the
    config for a submodule path. If no match is found it falls back to the
    current behaviour (module.$path).

Somehow I thought that it would make it ambiguous to have module.$name.path and module.$path when answering the question: "given a name of a module how would you find which path to bind it to".

But I do not think it is a problem; at least "ambiguity" worry is unfounded. This section, without "path = " line:

	[module "foo"]
        	url = ...

is equivalent to have "path = foo" in it. Finding path from module name is well defined.

The other, finding what module should go to a given path, is not well defined. IOW, you would not know which module you want at the path bar/ when you have:

	[module "foo"]
        	url = ...
                path = bar
	[module "bar"]
        	url = ...

But that problem exists with or without these "module.*.path and module.$path", so it cannot be an argument against the definition of the fallback behaviour.

Matthias Lederhofer· Jun 13, 2007, 15:36 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

Lars Hjemli <hjemli@gmail.com> wrote:
> +SYNOPSIS
> +--------
> +.gitmodules

My asciidoc (7.1.2 and 8.2.1) generates an empty refsynopsisdiv from this. xmlto refuses to convert this into anything else:

xmlto -m callouts.xsl man gitmodules.xml
xmlto: input does not validate (status 3)
/path/to/git/Documentation/gitmodules.xml:15: element refsynopsisdiv: validity error : Element refsynopsisdiv content does not follow the DTD, expecting (refsynopsisdivinfo? , (title , subtitle? , titleabbrev?)? , (((calloutlist | glosslist | itemizedlist | orderedlist | segmentedlist | simplelist | variablelist | caution | important | note | tip | warning | literallayout | programlisting | programlistingco | screen | screenco | screenshot | synopsis | cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis | constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara | para | simpara | address | blockquote | graphic | graphicco | mediaobject | mediaobjectco | informalequation | informalexample | informalfigure | informaltable | equation | example | figure | table | msgset | procedure | sidebar | qandaset | anchor | bridgehead | remark | highlights | abstract | authorblurb 
 | epigraph | indexterm | beginpage)+ , refsect2*) | refsect2+)), got ()
Document /path/to/git/Documentation/gitmodules.xml does not validate

This breaks the build process for the documentation. I could not find out how to fix this. Probably just needs the right quoting for the dot at the beginning of the line.

Lars Hjemli· Jun 13, 2007, 16:13 UTC · re: Matthias Lederhofer · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/13/07, Matthias Lederhofer <matled@gmx.net> wrote:
Show 7 quoted lines
> Lars Hjemli <hjemli@gmail.com> wrote:
> > +SYNOPSIS
> > +--------
> > +.gitmodules
>
> My asciidoc (7.1.2 and 8.2.1) generates an empty refsynopsisdiv from
> this.  xmlto refuses to convert this into anything else:
Sorry about that, I don't have a working asciidoc :-(

But looking through the latest asciidoc-doc suggests that .gitmodules is treated like a blocktitle: http://www.methods.co.nz/asciidoc/userguide.html#toc33

Could you please try one or both of the following escape-sequences?

\.gitmodules #.gitmodules#

Thanks

-- larsh

Matthias Lederhofer· Jun 13, 2007, 16:31 UTC · re: Lars Hjemli · lore

Re: [PATCH 2/3] Add gitmodules(5)

Lars Hjemli <hjemli@gmail.com> wrote:
> Could you please try one or both of the following escape-sequences?
> 
> \.gitmodules
> #.gitmodules#

#.gitmodules# seems to produce a good xml file, html is fine too. But the conversion from xml to a manpage seems to be broken:

    $ xmlto -m callouts.xsl man gitmodules.xml
transforms
    <refsynopsisdiv>
    <simpara>.gitmodules</simpara>
    </refsynopsisdiv>
to
    .SH "SYNOPSIS"
    .gitmodules

".gitmodules" is not shown in the manpage and vim highlights the ".gi" just like ".SH" in a special color. Perhaps we should just highlight .gitmodules like commands with single quotes. This solves both problems :)

Lars Hjemli· Jun 13, 2007, 16:59 UTC · re: Matthias Lederhofer · lore

Re: [PATCH 2/3] Add gitmodules(5)

On 6/13/07, Matthias Lederhofer <matled@gmx.net> wrote:
Show 28 quoted lines
> Lars Hjemli <hjemli@gmail.com> wrote:
> > Could you please try one or both of the following escape-sequences?
> >
> > \.gitmodules
> > #.gitmodules#
>
> #.gitmodules# seems to produce a good xml file, html is fine too.  But
> the conversion from xml to a manpage seems to be broken:
>
>     $ xmlto -m callouts.xsl man gitmodules.xml
>
> transforms
>
>     <refsynopsisdiv>
>     <simpara>.gitmodules</simpara>
>
>     </refsynopsisdiv>
>
> to
>
>     .SH "SYNOPSIS"
>     .gitmodules
>
> ".gitmodules" is not shown in the manpage and vim highlights the ".gi"
> just like ".SH" in a special color.  Perhaps we should just highlight
> .gitmodules like commands with single quotes.  This solves both
> problems :)
>

Ok, thanks for trying to clean up my mess. I guess there's a good reason why Junios examples drop the leading dot (cat /usr/share/man/man1/git-submodule.1 was an eyeopener for me right now ;-)

-- 
larsh
Junio C Hamano· Jun 13, 2007, 16:20 UTC · re: Matthias Lederhofer · lore

Re: [PATCH 2/3] Add gitmodules(5)

Matthias Lederhofer <matled@gmx.net> writes:
Show 11 quoted lines
> Lars Hjemli <hjemli@gmail.com> wrote:
>> +SYNOPSIS
>> +--------
>> +.gitmodules
>
> My asciidoc (7.1.2 and 8.2.1) generates an empty refsynopsisdiv from
> this.  xmlto refuses to convert this into anything else:
> ...
> This breaks the build process for the documentation.  I could not find
> out how to fix this.  Probably just needs the right quoting for the
> dot at the beginning of the line.

Sorry, I should have caught this much earlier, as already knew about this issue when I did gitattributes(5).

As it seems to be customary not to even say 'dot' at the beginning for man(5) section (existing examples I found are netrc, postgresrc, procmailrc, ...), I think the best fix is just to do s/\.gitmodules/gitmodules/ there.

Lars Hjemli· Jun 13, 2007, 22:01 UTC · re: Junio C Hamano · lore

[PATCH] gitmodules(5): remove leading period from synopsis

Asciidoc treats a line starting with a period followed by a title as a blocktitle element. My introduction of gitmodules(5) unfortunatly broke the documentation build process due to this processing, since it made asciidoc generate an illegal (empty) synopsis element. Removing the leading period fixes the problem and also makes gitmodules(5) use the same synopsis notation as gitattributes(5).

Noticed-by: Matthias Lederhofer <matled@gmx.net>
Signed-off-by: Lars Hjemli <hjemli@gmail.com>
---

Sorry for the breakage, I'll try to get asciidoc working before submitting any more patches to Documentation/.

 Documentation/gitmodules.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)
Show changes to Documentation/gitmodules.txt +1 −1
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 7814b6a..035294e 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -7,7 +7,7 @@ gitmodules - defining submodule properties
 
 SYNOPSIS
 --------
-.gitmodules
+gitmodules
 
 
 DESCRIPTION

-- 
1.5.2.1.914.gbd3a7
Lars Hjemli· Jun 9, 2007, 21:38 UTC · re: Lars Hjemli · lore

[PATCH 3/3] t7400: barf if git-submodule removes or replaces a file

The test for an unmolested file wouldn't fail properly if the file had been removed or replaced by something other than a regular file. This fixes it.

Signed-off-by: Lars Hjemli <hjemli@gmail.com>
---
 t/t7400-submodule-basic.sh |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)
Show changes to t/t7400-submodule-basic.sh +1 −1
diff --git a/t/t7400-submodule-basic.sh b/t/t7400-submodule-basic.sh
index 3940433..74fafce 100755
--- a/t/t7400-submodule-basic.sh
+++ b/t/t7400-submodule-basic.sh
@@ -72,7 +72,7 @@ test_expect_success 'update should fail when path is used by a file' '
 	then
 		echo "[OOPS] update should have failed"
 		false
-	elif test -f lib && test "$(cat lib)" != "hello"
+	elif test "$(cat lib)" != "hello"
 	then
 		echo "[OOPS] update failed but lib file was molested"
 		false

-- 
1.5.2.1.914.gbd3a7

← back to recent threads