On Sun, Jun 18, 2017 at 10:24 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Stefan, this was sent in my way, but I know you are the primary > person who is looking into updating submodule documentation these > days, so I am forwarding it in your way to ask you to give the first > comment. > > Thanks. AFAICT this is specific to the arguments of 'add', such that it would not collide with sb/submodule-doc[1]. However my series was RFC, while this is on the order of "documentation bug fix", so this would be more important than rewriting the documentation from scrach any way. :) [1] https://public-inbox.org/git/20170607185354.10050-1-sbeller@xxxxxxxxxx/ > > Kaartic Sivaraam <kaarticsivaraam91196@xxxxxxxxx> writes: > >> 1. Remove redundancy from documentation >> 2. Remove unclear reference to alternative >> >> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@xxxxxxxxx> >> --- >> >> The following line seemes unclear and hence was removed for now. Suggest any >> changes that could make it clear. >> >> "This second form is provided to ease creating a new submodule from scratch, >> and presumes the user will later push the submodule to the given URL." +cc Marc who wrote this sentence originally. >> >> >> Documentation/git-submodule.txt | 37 ++++++++++++++++--------------------- >> 1 file changed, 16 insertions(+), 21 deletions(-) >> >> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt >> index 74bc6200d..9812b0655 100644 >> --- a/Documentation/git-submodule.txt >> +++ b/Documentation/git-submodule.txt >> @@ -63,13 +63,7 @@ add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--dep >> to the changeset to be committed next to the current >> project: the current project is termed the "superproject". >> + >> -This requires at least one argument: <repository>. The optional >> -argument <path> is the relative location for the cloned submodule >> -to exist in the superproject. If <path> is not given, the >> -"humanish" part of the source repository is used ("repo" for >> -"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). >> -The <path> is also used as the submodule's logical name in its >> -configuration entries unless `--name` is used to specify a logical name. >> +This requires at least one argument: <repository>. >> + So we're losing the information how the submodule name is chosen. This may be fine as I plan (long term) to make the name an arbitrary random string (IMHO that reduces confusion as there will be less 'nearly the same' things) On the other hand the newly added line 'This requires at least one argument: <repository' (actually moved, but) is sort of redundant. The notation in the argument line should make that clear, already? >> <repository> is the URL of the new submodule's origin repository. >> This may be either an absolute URL, or (if it begins with ./ >> @@ -87,21 +81,22 @@ If the superproject doesn't have a default remote configured >> the superproject is its own authoritative upstream and the current >> working directory is used instead. >> + >> -<path> is the relative location for the cloned submodule to >> -exist in the superproject. If <path> does not exist, then the >> -submodule 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 creating a new submodule from scratch, and presumes >> -the user will later push the submodule to the given URL. >> +The optional argument <path> is the relative location for the cloned >> +submodule to exist in the superproject. If <path> is not given, the >> +"humanish" part of the source repository is used ("repo" for >> +"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path> >> +exists and is already a valid Git repository, then this is added >> +to the changeset without cloning. The <path> is also used as the >> +submodule's logical name in its configuration entries unless `--name` >> +is used to specify a logical name. This sounds good, it consolidates all information about [<path>] in one paragraph. While at it, maybe let's find another (better) substitute for "humanish" as that can be anything(?). Maybe "the last part of the URL" (without any .git) >> + >> -In either case, the given URL is recorded into .gitmodules for >> -use by subsequent users cloning the superproject. If the URL is >> -given relative to the superproject's repository, the presumption >> -is the superproject and submodule repositories will be kept >> -together in the same relative location, and only the >> -superproject's URL needs to be provided: git-submodule will correctly >> -locate the submodule using the relative URL in .gitmodules. >> +The given URL is recorded into .gitmodules for use by subsequent users >> +cloning the superproject. If the URL is given relative to the >> +superproject's repository, the presumption is the superproject and >> +submodule repositories will be kept together in the same relative >> +location, and only the superproject's URL needs to be provided. >> +git-submodule will correctly locate the submodule using the relative >> +URL in .gitmodules. >> (While at it:) Please markup the '.gitmodules' either via single quotes or `. (or even link to 'gitmodules(5)' ) >> status [--cached] [--recursive] [--] [<path>...]:: >> Show the status of the submodules. This will print the SHA-1 of the I am undecided if this is really removing (2) unclearness, but the (1) redundancy seems fine to me. Thanks, Stefan