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

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

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

+	[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 [off-list ref]
www: http://www.djpig.de/