Mark Levedahl <mlevedahl@xxxxxxxxx> writes:
> 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/\$/& /;
> 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.
> 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.
> + <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/;
> @@ -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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
