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

[Frank Lichtenheld <frank@lichtenheld.de>]

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 <frank@lichtenheld.de>
www: http://www.djpig.de/