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

From: Frank Lichtenheld <frank@lichtenheld.de>
Date: Jun 10, 2007, 00:28 UTC
Message-ID: <20070610002802.GD31707@planck.djpig.de>
In-Reply-To: <11814251322779-git-send-email-hjemli@gmail.com>

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/