Re: [PATCH] Clarify role of init command in git-submodules documentation

[Sven Verdoolaege <skimo@kotnet.org>]

On Mon, Aug 20, 2007 at 09:09:44AM +0200, martin f. krafft wrote:
>  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 "submodule.$name.url".
> +To work with submodules, a user has to prepare a repository clone with the

I think this is a bit ambiguous.

> +command `git-submodule init`. This command copies the url of each submodule

As you can see in the "init" section of the man pages, the url is only
copied if it's not there already.

> +listed in the .gitmodules file in the top-level directory of the containing
> +repository to $GIT_DIR/config. The key to each submodule url is
> +"submodule.$name.url".
> +
> +The .gitmodules file then specifies the location of each submodule with
> +respect to the repository (and is shared among all contributors), while the
> +url of each submodule comes from the local configuration in $GIT_DIR/config
> +and can thus be modified independently of all other users.

This is better than the previous version, but in my mind still a bit confusing.
Let me have a go:

.gitmodules::
	This file specifies the location of each submodule with respect
	to the top-level directory of the git working tree as well as
	the default url of each submodule.  This default url is ignored
	by all git submodule subcommands, except init.  The latter can
	be used to initialize the url in $GIR_DIR/config, which is the
	url used by the other subcommands.  This file is typically
	tracked as it contains information that is shared by all
	contributors.  See also: gitlink:gitmodules[5].

$GIT_DIR/config::
	This files contains the url of each submodule in "submodule.$name.url".
	These urls are required by git submodule subcommands such as update
	and can be initialized by calling "git submodule init".
	The urls are specified in the local $GIT_DIR/config as the most
	appropriate url to get updates from may by different for different users
	and should not depend on the particular revision of the superproject
	that is currently checked out.

skimo