Re: [PATCH] git-submodule - make "submodule add" more strict, and document it

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 9, 2008, 06:04 UTC
Message-ID: <7vwsjvlhjw.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1215575965-3588-1-git-send-email-mlevedahl@gmail.com>

Mark Levedahl <mlevedahl@gmail.com> writes:

Show 5 quoted lines

> This change makes "submodule add" much more strict in the arguments it
> takes, and is intended to address confusion as recently noted on the
> git-list. With this change, the required syntax is:
> 	$ git submodule add URL path
>

Please have an extra blank line on both sides of examples.

> Specifically, this eliminates the form
> 	$git submodule add URL
> which was confused by more than one person as
> 	$git submodule add path

s/\$/& /;

Show 8 quoted lines

> The change eliminates one form of URL: a path relative to the current
> working directory....
> ...
> Following this change, there are exactly four variants of
> submodule-add, as both arguments have two flavors:
>
> URL can be absolute, or can begin with ./|../ and thus name the origin
> relative to the top-level origin.

Now this _is_ confusing. Examples of a path relative to the current working directory would be ./foo or ../../foo but the previous paragraph says the form is eliminated. I think I know what you want to say, but it still is confusing.

Show 7 quoted lines

>  add::
>  	Add the given repository as a submodule at the given path
> +	to the changeset to be committed next. This requires two arguments,
> +	<repository> and <path>. <repository> is the URL of the new
> +	submodule's origin repository. This may be either an absolute URL,
> +	or (if it begins with ./ or ../), the location relative
> +	to the parent repository's origin.

This is much better than the part I found confusing above. Here, "parent repository" actually means "this repository", right? It is the one that owns the index you are adding the gitlink to and tracks the .gitmodules file you are adding an entry for this submodule to.

Show 11 quoted lines

> +	<path> is the relative location for the cloned submodule to
> +	exist in the current tree. If <path> does not exist, then the
> +	module is created by cloning from the named URL. If <path> does
> +	exist and is already a valid git repository, then this is added
> +	to the changeset without cloning. This second form is provided
> +	to ease adding a submodule to a project the first time, and presumes
> +	the user will later push the new submodule to the given URL.
> +
> +	In either case, the given URL is recorded into .gitmodules for
> +	use by subsequent users cloning the project. If the URL is given
> +	relative to the parent, the presumption is the main and sub-modules

We seem to say "superproject" and "submodule" elsewhere, including Linus's talk.

> +	will be kept together in the same relative location, and only the
> +	top-level URL need be provided: git-submodule will correctly
> +	locat the submodules using the hint in .gitmodules.

s/locat/&e/;

Show 9 quoted lines

> @@ -150,16 +138,27 @@ cmd_add()
> ...
> +	# assure repo is absolute or relative to parent
> +	case "$repo" in
> +		./*|../*)
> +			# dereference source url relative to parent's url
> +			realrepo=$(resolve_relative_url "$repo") || exit
> +			;;
> +	    *:*|/*)

Funny indentation; "case/esac" and its arms align, like so:

	case "$repo" in
        ./* | ../*)
        	...
		;;
	esac