submodule improvements
cover 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(-)
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.
---
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%)Documentation/git-submodule.txt +10 -6
@@ -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 ------
git-submodule.sh +30 -14
92 lines not on this page · raw message
t/t7401-submodule-named.sh renamed from t/t7400-submodule-basic.sh +19 -8
@@ -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
Signature · 1 line
1.5.2.1.914.gbd3a7
Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ
Quoted 3 lines · Lars Hjemli
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?
Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ
Quoted 9 lines · Junio C Hamano
Quoted 3 lines · Lars Hjemli
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.
Signature · 1 line
larsh
Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ
In reply to Junio C HamanoHi,
Quoted 9 lines · Junio C Hamano
Quoted 3 lines · Lars Hjemli
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
Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ
Quoted 8 lines · Johannes Schindelin
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Lars Hjemli
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).
Quoted 8 lines
Quoted 3 lines
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.
Re: [PATCH 1/3] git-submodule: allow submodule name and path to differ
Quoted 24 lines · Junio C Hamano
Quoted 8 lines · Johannes Schindelin
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Lars Hjemli
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).
Quoted 8 lines
Quoted 3 lines
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.
Quoted 8 lines
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 :)
Signature · 1 line
larsh
PATCH 2/3 Add gitmodules(5)
In reply to Lars HjemliThis adds documentation for the .gitmodules file.
--- Documentation/Makefile | 2 +- Documentation/gitmodules.txt | 63 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletions(-) create mode 100644 Documentation/gitmodules.txt
Documentation/Makefile +1 -1
@@ -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))
Documentation/gitmodules.txt new file +63 -0
63 lines not on this page · raw message
Signature · 1 line
1.5.2.1.914.gbd3a7
Re: [PATCH 2/3] Add gitmodules(5)
The unofficial git documentation nitpicker at work ;)
Documentation/gitmodules.txt line 17
Quoted 2 lines · Lars Hjemli
Documentation/gitmodules.txt new file +2
-0+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".
Documentation/gitmodules.txt line 22
Quoted 5 lines
Documentation/gitmodules.txt new file +5
-0+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.
Documentation/gitmodules.txt line 31
Quoted 8 lines
Documentation/gitmodules.txt new file +8
-0+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.
Documentation/gitmodules.txt line 44
Quoted 6 lines
Documentation/gitmodules.txt new file +6
-0+ [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,
Signature · 2 lines
Frank Lichtenheld <[email protected]> www: http://www.djpig.de/
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 1 line · Frank Lichtenheld
The unofficial git documentation nitpicker at work ;)
That's good, keep it up :)
Quoted 6 lines · Lars Hjemli
Documentation/gitmodules.txt line 17
Quoted 2 lines
Documentation/gitmodules.txt new file +2
-0+The `.gitmodules` file, located in the top-level directory of a +gitlink:git[7] working tree, is a text file with a layout matching theThat 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.
Quoted 1 line
I would have used "syntax" instead of "layout".
Agreed
Quoted 12 lines
Documentation/gitmodules.txt line 22
Quoted 6 lines
Documentation/gitmodules.txt new file +5
-0+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 sectionmodule, one per submodule"? Hmm, sounds ugly too.
Good documentation is hard, so I'll work on it some more...
Quoted 11 lines
Documentation/gitmodules.txt line 31
Quoted 9 lines
Documentation/gitmodules.txt new file +8
-0+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.
Quoted 7 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!
Quoted 10 lines
Documentation/gitmodules.txt line 44
Quoted 7 lines
Documentation/gitmodules.txt new file +6
-0+ [module 'libfoo'] + path = include/foo + url = git://example1.com/git/libfoo.git + + [module 'libbar'] + url = git://example2.com/pub/git/libbar.gitThis 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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 12 lines · Lars Hjemli
Quoted 10 lines · Frank Lichtenheld
Documentation/gitmodules.txt line 31
Quoted 8 lines
Documentation/gitmodules.txt new file +8
-0+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.
Quoted 2 lines
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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 13 lines · Sven Verdoolaege
Quoted 12 lines · Lars Hjemli
Quoted 10 lines · Frank Lichtenheld
Documentation/gitmodules.txt line 31
Quoted 8 lines
Documentation/gitmodules.txt new file +8
-0+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.
Quoted 4 lines
Quoted 2 lines
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
Quoted 10 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.
Quoted 2 lines
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
Quoted 1 line
Other than that, I like it.
Thanks :)
Quoted 2 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? 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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 11 lines · Lars Hjemli
Quoted 7 lines · Sven Verdoolaege
Quoted 4 lines · Lars Hjemli
Quoted 1 line
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?
Quoted 8 lines
Quoted 2 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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 8 lines · Sven Verdoolaege
Quoted 7 lines · Lars Hjemli
Quoted 6 lines · Sven Verdoolaege
Quoted 4 lines · Lars Hjemli
Quoted 1 line
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.
Quoted 6 lines
Quoted 4 lines
Quoted 1 line
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/49620Euhm... this just points back to this thread...
I know ;-)
Quoted 2 lines
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.
Quoted 4 lines
Quoted 4 lines
Quoted 3 lines
It doesn't have the extensions proposed by Linus, but it seems to be forward compatible with them.
Quoted 8 lines
Quoted 5 lines
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
Re: [PATCH 2/3] Add gitmodules(5)
In reply to Lars HjemliQuoted 5 lines · Lars Hjemli
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.
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 8 lines · Junio C Hamano
Quoted 5 lines · Lars Hjemli
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'.
Quoted 5 lines
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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 3 lines · Lars Hjemli
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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 6 lines · Sven Verdoolaege
Quoted 3 lines · Lars Hjemli
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
Quoted 1 line
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:
git-submodule.sh +0 -0
@@ -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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 6 lines · Lars Hjemli
Quoted 5 lines · Sven Verdoolaege
Quoted 3 lines · Lars Hjemli
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.
Quoted 7 lines
Quoted 1 line
So every (sub)module subsection will have to have a path element?
Yes
Quoted 1 line
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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 5 lines · Sven Verdoolaege
Quoted 3 lines
Quoted 1 line
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.
Re: [PATCH 2/3] Add gitmodules(5)
In reply to Lars HjemliHi,
Quoted 1 line · Lars Hjemli
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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 9 lines · Johannes Schindelin
Hi,
Quoted 1 line · Lars Hjemli
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" :)
Signature · 1 line
larsh
Re: [PATCH 2/3] Add gitmodules(5)
In reply to Lars HjemliQuoted 3 lines · Lars Hjemli
+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.
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 11 lines · Matthias Lederhofer
Quoted 3 lines · Lars Hjemli
+SYNOPSIS
+--------
+.gitmodulesMy 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.
PATCH 1/1 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).
---
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(-)
Documentation/gitmodules.txt +1 -1
@@ -7,7 +7,7 @@ gitmodules - defining submodule properties SYNOPSIS -------- -.gitmodules +gitmodules DESCRIPTION
Signature · 1 line
1.5.2.1.914.gbd3a7
Re: [PATCH 2/3] Add gitmodules(5)
In reply to Matthias LederhoferQuoted 7 lines · Matthias Lederhofer
Quoted 3 lines · Lars Hjemli
+SYNOPSIS
+--------
+.gitmodulesMy 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
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 4 lines · Lars Hjemli
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 :)
Re: [PATCH 2/3] Add gitmodules(5)
Quoted 20 lines · Matthias Lederhofer
Quoted 4 lines · Lars Hjemli
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.xmltransforms
<refsynopsisdiv>
<simpara>.gitmodules</simpara></refsynopsisdiv>
to
Quoted 8 lines
.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 ;-)
Signature · 1 line
larsh
PATCH 3/3 t7400: barf if git-submodule removes or replaces a file
In reply to Lars HjemliThe 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.
--- t/t7400-submodule-basic.sh | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-)
t/t7400-submodule-basic.sh +1 -1
@@ -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
Signature · 1 line
1.5.2.1.914.gbd3a7