[PATCH/RFC] Cleanup Documentation

[PATCH/RFC] Cleanup Documentation

[Kaartic Sivaraam]

1. Remove redundancy from documentation
2. Remove unclear reference to alternative

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---

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."


 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>.
 +
 <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.
 +
-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.
 
 status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1 of the
-- 
2.11.0

Re: [PATCH/RFC] Cleanup Documentation

[Junio C Hamano]

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.

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> 1. Remove redundancy from documentation
> 2. Remove unclear reference to alternative
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>
> 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."
>
>
>  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>.
>  +
>  <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.
>  +
> -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.
>  
>  status [--cached] [--recursive] [--] [<path>...]::
>  	Show the status of the submodules. This will print the SHA-1 of the

Re: [PATCH/RFC] Cleanup Documentation

[Stefan Beller]

On Sun, Jun 18, 2017 at 10:24 PM, Junio C Hamano <gitster@pobox.com> 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@google.com/


>
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> 1. Remove redundancy from documentation
>> 2. Remove unclear reference to alternative
>>
>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>> ---
>>
>> 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

Re: [PATCH/RFC] Cleanup Documentation

[Kaartic Sivaraam]

On Sun, 2017-06-18 at 22:50 -0700, Stefan Beller wrote:
> > > 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.
I just moved it. I don't think we're losing anything related to how the
name is chosen. Please let me know if I misinterpreted your statement.

> 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?
> 
Makes clear sense. Removed it.

> 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)
> 
How about "meaningful"? Put in place it reads like,

If <path> is not given, the meaningful part of the source repository
...

> Please markup the '.gitmodules' either via single quotes or `.
> (or even link to 'gitmodules(5)' )
> 
Marked it up using `. Help needed to link to 'gitmodules(5)', as I'm
not sure how to provide alternative text to 'linkgit:'.

> I am undecided if this is really removing (2) unclearness, but the
> (1) redundancy seems fine to me.
> 
Sorry about that. The commit message should have been,

...
2. Removed unclear back reference
...

by which I intend to denote the following removal,
> -In either case, the given URL is recorded into .gitmodules for
> -use by subsequent users cloning the superproject.

Note: Will follow up with a patch, soon.
-- 
Regards,
Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

Re: [PATCH/RFC] Cleanup Documentation

[Stefan Beller]

On Mon, Jun 19, 2017 at 10:33 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:

>
>> Please markup the '.gitmodules' either via single quotes or `.
>> (or even link to 'gitmodules(5)' )
>>
> Marked it up using `. Help needed to link to 'gitmodules(5)', as I'm
> not sure how to provide alternative text to 'linkgit:'.

I did not mean  'gitmodules(5)' literally, I rather meant using linkgit:
as you know it. :)

>
>> I am undecided if this is really removing (2) unclearness, but the
>> (1) redundancy seems fine to me.
>>
> Sorry about that. The commit message should have been,
>
> ...
> 2. Removed unclear back reference

Oh that clears some confusion here. :)

> Note: Will follow up with a patch, soon.

Thanks.
Stefan

[PATCH/RFC] Cleanup Documentation

[Kaartic Sivaraam]

Make following changes to the git-submodule
documentation:

* Remove redundancy
* Remove unclear back reference
* Use more appropriate word
* Quote important word

Suggestions-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Currently used the word "canonical" instead of "humanish". If that word
 sounds more suitable then this is a [PATCH] and not a [PATCH/RFC].


 Documentation/git-submodule.txt | 37 +++++++++++++++----------------------
 1 file changed, 15 insertions(+), 22 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 74bc6200d..045fef417 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -63,14 +63,6 @@ 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.
-+
 <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 superproject's default remote
@@ -87,21 +79,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
+canonical 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.
 +
-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.
 
 status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1 of the
-- 
2.11.0

Re: [PATCH/RFC] Cleanup Documentation

[Stefan Beller]

On Mon, Jun 19, 2017 at 8:12 PM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> Make following changes to the git-submodule
> documentation:
>
> * Remove redundancy
> * Remove unclear back reference
> * Use more appropriate word
> * Quote important word
>
> Suggestions-by: Stefan Beller <sbeller@google.com>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Currently used the word "canonical" instead of "humanish". If that word
>  sounds more suitable then this is a [PATCH] and not a [PATCH/RFC].

canonical: "according to recognized rules or scientific laws."
sounds about right. :)

>
>  Documentation/git-submodule.txt | 37 +++++++++++++++----------------------
>  1 file changed, 15 insertions(+), 22 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 74bc6200d..045fef417 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -63,14 +63,6 @@ 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.
> -+
>  <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 superproject's default remote
> @@ -87,21 +79,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
> +canonical 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.

While this was just reflowed and not newly introduced, I am still left
wondering what a changeset is in Git terms. Our Documentation/glossary
says:

  [[def_changeset]]changeset::
  BitKeeper/cvsps speak for "<<def_commit,commit>>". Since Git does not
  store changes, but states, it really does not make sense to use the term
  "changesets" with Git.

Maybe we should say instead:

    If <path>exists and is already a valid Git repository,
    then this is staged for commit 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.
>  +
> -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.
>

With or without this nit addressed, this patch looks good to me,

Thanks,
Stefan

Re: [PATCH/RFC] Cleanup Documentation

[Stefan Beller]

On Tue, Jun 20, 2017 at 9:57 AM, Stefan Beller <sbeller@google.com> wrote:
>
> With or without this nit addressed, this patch looks good to me,
>

Well actually not quite. The subject (and commit message) is very vague,
maybe:

    Documentation/git-submodule: cleanup "add" section

    The "add" section for 'git-submodule' is redundant in its description and
    the short synopsis line. Remove the redundant mentioning of the
    'repository' argument being mandatory.

    The text is hard to read because of back-references, so remove those.

    Replace the word "humanish" by "canonical" as that conveys better what
    we do to guess the path.

    While at it, quote all occurrences of '.gitmodules' as that is an important
    file in the submodule context, also link to it on its first mention.
    (This paragraph is not exactly what happens in the commit, but I wrote it
    as a way how I would write commit messages. It shows the reader how
    you addressed the given problem, with the quantifiers "all" "the
first" showing
    what you think is important, and that you deliberately omitted others)

Re: [PATCH/RFC] Cleanup Documentation

[Kaartic Sivaraam]

On Tue, 2017-06-20 at 09:57 -0700, Stefan Beller wrote:
> canonical: "according to recognized rules or scientific laws."
> sounds about right. :)
> 
I actually used as I found it to have the meaning of "conforming to
orthodox or recognized rules" :)


> While this was just reflowed and not newly introduced, I am still
> left wondering what a changeset is in Git terms. Our
> Documentation/glossary says:
> 
>   [[def_changeset]]changeset::
>   BitKeeper/cvsps speak for "<<def_commit,commit>>". Since Git does
> not store changes, but states, it really does not make sense to use
> the term "changesets" with Git.
> 
> Maybe we should say instead:
> 
>     If <path>exists and is already a valid Git repository,
>     then this is staged for commit without cloning.
> 
Does seem to be a good change to make. Done.

On Tue, 2017-06-20 at 10:05 -0700, Stefan Beller wrote:
> > On Tue, Jun 20, 2017 at 9:57 AM, Stefan Beller <sbeller@google.com>
> > wrote:
> > > 
> > > With or without this nit addressed, this patch looks good to me,
> > > 
> > 
> > Well actually not quite. The subject (and commit message) is very
> > vague,
> > maybe:
> 
> >     Documentation/git-submodule: cleanup "add" section
> > 
> >     The "add" section for 'git-submodule' is redundant in its
> > description and
> >     the short synopsis line. Remove the redundant mentioning of the
> >     'repository' argument being mandatory.
> > 
> >     The text is hard to read because of back-references, so remove
> > those.
> > 
> >     Replace the word "humanish" by "canonical" as that conveys
> better
> > what
> >     we do to guess the path.
> > 
> >     While at it, quote all occurrences of '.gitmodules' as that is
> an
> > important
> >     file in the submodule context, also link to it on its first
> > mention.
> >     (This paragraph is not exactly what happens in the commit, but
> I
> > wrote it
> >     as a way how I would write commit messages. It shows the reader
> > how
> >     you addressed the given problem, with the quantifiers "all"
> "the
> > first" showing
> >     what you think is important, and that you deliberately omitted
> > others)
> 
Made this change too.


-- 
Regards,
Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

[PATCH/FINALRFC] Documentation/git-submodule: cleanup

[Kaartic Sivaraam]

The "add" section for 'git-submodule' is redundant in
its description and the short synopsis line. Fix it.

Remove the redundant mentioning of the 'repository' argument
being mandatory.

The text is hard to read because of back-references, so remove
those.

Replace the word "humanish" by "canonical" as that conveys better
what we do to guess the path.

While at it, quote all occurrences of '.gitmodules' as that is an
important file in the submodule context, also link to it on its
first mention.

Helped-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 In case no other changes are required then this is the final version
 of the patch.


 Documentation/git-submodule.txt | 49 ++++++++++++++++++---------------
--------
 1 file changed, 21 insertions(+), 28 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-
submodule.txt
index 74bc6200d..6e07bade3 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -63,14 +63,6 @@ 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.
-+
 <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 superproject's default remote
@@ -87,21 +79,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
+canonical 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 it is staged
+for commit 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.
 +
-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`.
 
 status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1
of the
@@ -123,7 +116,7 @@ too (and can also report changes to a submodule's
work tree).
 init [--] [<path>...]::
 	Initialize the submodules recorded in the index (which were
 	added and committed elsewhere) by setting
`submodule.$name.url`
-	in .git/config. It uses the same setting from .gitmodules as
+	in .git/config. It uses the same setting from `.gitmodules` as
 	a template. If the URL is relative, it will be resolved using
 	the default remote. If there is no default remote, the current
 	repository will be assumed to be upstream.
@@ -197,7 +190,7 @@ configuration variable:
 	none;; the submodule is not updated.
 
 If the submodule is not yet initialized, and you just want to use the
-setting as stored in .gitmodules, you can automatically initialize the
+setting as stored in `.gitmodules`, you can automatically initialize
the
 submodule with the `--init` option.
 
 If `--recursive` is specified, this command will recurse into the
@@ -220,7 +213,7 @@ foreach [--recursive] <command>::
 	Evaluates an arbitrary shell command in each checked out
submodule.
 	The command has access to the variables $name, $path, $sha1
and
 	$toplevel:
-	$name is the name of the relevant submodule section in
.gitmodules,
+	$name is the name of the relevant submodule section in
`.gitmodules`,
 	$path is the name of the submodule directory relative to the
 	superproject, $sha1 is the commit as recorded in the
superproject,
 	and $toplevel is the absolute path to the top-level of the
superproject.
@@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse
HEAD`'
 
 sync [--recursive] [--] [<path>...]::
 	Synchronizes submodules' remote URL configuration setting
-	to the value specified in .gitmodules. It will only affect
those
+	to the value specified in `.gitmodules`. It will only affect
those
 	submodules which already have a URL entry in .git/config (that
is the
 	case when they are initialized or freshly added). This is
useful when
 	submodule URLs change upstream and you need to update your
local
@@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `
--shared` options carefully.
 --[no-]recommend-shallow::
 	This option is only valid for the update command.
 	The initial clone of a submodule will use the recommended
-	`submodule.<name>.shallow` as provided by the .gitmodules file
+	`submodule.<name>.shallow` as provided by the `.gitmodules`
file
 	by default. To ignore the suggestions use `--no-recommend-
shallow`.
 
 -j <n>::
@@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `
--shared` options carefully.
 
 FILES
 -----
-When initializing submodules, a .gitmodules file in the top-level
directory
+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 `$GIT_DIR/config`.
The key
 to each submodule url is "submodule.$name.url".  See
linkgit:gitmodules[5]
-- 
2.11.0

Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Helped-by: Stefan Beller <sbeller@google.com>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  In case no other changes are required then this is the final version
>  of the patch.
>
>
>  Documentation/git-submodule.txt | 49 ++++++++++++++++++---------------
> --------
>  1 file changed, 21 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-
> submodule.txt
> index 74bc6200d..6e07bade3 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -63,14 +63,6 @@ add [-b <branch>] [-f|--force] [--name <name>] [
> --reference <repository>] [--dep

The patch is heavily line-wrapped and whitespace broken, unlike
previous patch messages you sent to the list.  

Did you do something differently?

Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup

[Kaartic Sivaraam]

On Wed, 2017-06-21 at 09:11 -0700, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
> 
> > Helped-by: Stefan Beller <sbeller@google.com>
> > Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> > ---
> >  In case no other changes are required then this is the final
> > version
> >  of the patch.
> > 
> > 
> >  Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------
> > ----
> > --------
> >  1 file changed, 21 insertions(+), 28 deletions(-)
> > 
> > diff --git a/Documentation/git-submodule.txt b/Documentation/git-
> > submodule.txt
> > index 74bc6200d..6e07bade3 100644
> > --- a/Documentation/git-submodule.txt
> > +++ b/Documentation/git-submodule.txt
> > @@ -63,14 +63,6 @@ add [-b <branch>] [-f|--force] [--name <name>] [
> > --reference <repository>] [--dep
> 
> The patch is heavily line-wrapped and whitespace broken, unlike
> previous patch messages you sent to the list.  
> 
> Did you do something differently?
Yes. Sorry about that. Due to some issue with the firewall in the
network I use, I couldn't send patches using 'send-email' so I used the
email-client (evolution) to send the patch believing it wouldn't damage
it. It crapped with the formatting. Sorry again, will be careful in
future (for which I have to find a work-around).

-- 
Regards,
Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>

[PATCH/FINAL] Documentation/git-submodule: cleanup

[Kaartic Sivaraam]

The "add" section for 'git-submodule' is redundant in
its description and the short synopsis line. Fix it.

Remove the redundant mentioning of the 'repository' argument
being mandatory.

The text is hard to read because of back-references, so remove
those.

Replace the word "humanish" by "canonical" as that conveys better
what we do to guess the path.

While at it, quote all occurrences of '.gitmodules' as that is an
important file in the submodule context, also link to it on its
first mention.

Helped-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------------------
 1 file changed, 21 insertions(+), 28 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 74bc6200d564c..6e07bade39a7c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -63,14 +63,6 @@ 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.
-+
 <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 superproject's default remote
@@ -87,21 +79,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
+canonical 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 it is staged
+for commit 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.
 +
-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`.
 
 status [--cached] [--recursive] [--] [<path>...]::
 	Show the status of the submodules. This will print the SHA-1 of the
@@ -123,7 +116,7 @@ too (and can also report changes to a submodule's work tree).
 init [--] [<path>...]::
 	Initialize the submodules recorded in the index (which were
 	added and committed elsewhere) by setting `submodule.$name.url`
-	in .git/config. It uses the same setting from .gitmodules as
+	in .git/config. It uses the same setting from `.gitmodules` as
 	a template. If the URL is relative, it will be resolved using
 	the default remote. If there is no default remote, the current
 	repository will be assumed to be upstream.
@@ -197,7 +190,7 @@ configuration variable:
 	none;; the submodule is not updated.
 
 If the submodule is not yet initialized, and you just want to use the
-setting as stored in .gitmodules, you can automatically initialize the
+setting as stored in `.gitmodules`, you can automatically initialize the
 submodule with the `--init` option.
 
 If `--recursive` is specified, this command will recurse into the
@@ -220,7 +213,7 @@ foreach [--recursive] <command>::
 	Evaluates an arbitrary shell command in each checked out submodule.
 	The command has access to the variables $name, $path, $sha1 and
 	$toplevel:
-	$name is the name of the relevant submodule section in .gitmodules,
+	$name is the name of the relevant submodule section in `.gitmodules`,
 	$path is the name of the submodule directory relative to the
 	superproject, $sha1 is the commit as recorded in the superproject,
 	and $toplevel is the absolute path to the top-level of the superproject.
@@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse HEAD`'
 
 sync [--recursive] [--] [<path>...]::
 	Synchronizes submodules' remote URL configuration setting
-	to the value specified in .gitmodules. It will only affect those
+	to the value specified in `.gitmodules`. It will only affect those
 	submodules which already have a URL entry in .git/config (that is the
 	case when they are initialized or freshly added). This is useful when
 	submodule URLs change upstream and you need to update your local
@@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
 --[no-]recommend-shallow::
 	This option is only valid for the update command.
 	The initial clone of a submodule will use the recommended
-	`submodule.<name>.shallow` as provided by the .gitmodules file
+	`submodule.<name>.shallow` as provided by the `.gitmodules` file
 	by default. To ignore the suggestions use `--no-recommend-shallow`.
 
 -j <n>::
@@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
 
 FILES
 -----
-When initializing submodules, a .gitmodules file in the top-level directory
+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 `$GIT_DIR/config`. The key
 to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]

--
https://github.com/git/git/pull/377

Re: [PATCH/FINAL] Documentation/git-submodule: cleanup

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> The "add" section for 'git-submodule' is redundant in
> its description and the short synopsis line. Fix it.
>
> Remove the redundant mentioning of the 'repository' argument
> being mandatory.
>
> The text is hard to read because of back-references, so remove
> those.
>
> Replace the word "humanish" by "canonical" as that conveys better
> what we do to guess the path.
>
> While at it, quote all occurrences of '.gitmodules' as that is an
> important file in the submodule context, also link to it on its
> first mention.
>
> Helped-by: Stefan Beller <sbeller@google.com>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---

Stefan, do you want to add a Reviewed-by: to this one?  I've scanned
it over and overall it looked OK (iow I didn't find anything worth
complaining about).

Thanks.

>  Documentation/git-submodule.txt | 49 ++++++++++++++++++-----------------------
>  1 file changed, 21 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 74bc6200d564c..6e07bade39a7c 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -63,14 +63,6 @@ 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.
> -+
>  <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 superproject's default remote
> @@ -87,21 +79,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
> +canonical 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 it is staged
> +for commit 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.
>  +
> -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`.
>  
>  status [--cached] [--recursive] [--] [<path>...]::
>  	Show the status of the submodules. This will print the SHA-1 of the
> @@ -123,7 +116,7 @@ too (and can also report changes to a submodule's work tree).
>  init [--] [<path>...]::
>  	Initialize the submodules recorded in the index (which were
>  	added and committed elsewhere) by setting `submodule.$name.url`
> -	in .git/config. It uses the same setting from .gitmodules as
> +	in .git/config. It uses the same setting from `.gitmodules` as
>  	a template. If the URL is relative, it will be resolved using
>  	the default remote. If there is no default remote, the current
>  	repository will be assumed to be upstream.
> @@ -197,7 +190,7 @@ configuration variable:
>  	none;; the submodule is not updated.
>  
>  If the submodule is not yet initialized, and you just want to use the
> -setting as stored in .gitmodules, you can automatically initialize the
> +setting as stored in `.gitmodules`, you can automatically initialize the
>  submodule with the `--init` option.
>  
>  If `--recursive` is specified, this command will recurse into the
> @@ -220,7 +213,7 @@ foreach [--recursive] <command>::
>  	Evaluates an arbitrary shell command in each checked out submodule.
>  	The command has access to the variables $name, $path, $sha1 and
>  	$toplevel:
> -	$name is the name of the relevant submodule section in .gitmodules,
> +	$name is the name of the relevant submodule section in `.gitmodules`,
>  	$path is the name of the submodule directory relative to the
>  	superproject, $sha1 is the commit as recorded in the superproject,
>  	and $toplevel is the absolute path to the top-level of the superproject.
> @@ -242,7 +235,7 @@ git submodule foreach 'echo $path `git rev-parse HEAD`'
>  
>  sync [--recursive] [--] [<path>...]::
>  	Synchronizes submodules' remote URL configuration setting
> -	to the value specified in .gitmodules. It will only affect those
> +	to the value specified in `.gitmodules`. It will only affect those
>  	submodules which already have a URL entry in .git/config (that is the
>  	case when they are initialized or freshly added). This is useful when
>  	submodule URLs change upstream and you need to update your local
> @@ -413,7 +406,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
>  --[no-]recommend-shallow::
>  	This option is only valid for the update command.
>  	The initial clone of a submodule will use the recommended
> -	`submodule.<name>.shallow` as provided by the .gitmodules file
> +	`submodule.<name>.shallow` as provided by the `.gitmodules` file
>  	by default. To ignore the suggestions use `--no-recommend-shallow`.
>  
>  -j <n>::
> @@ -429,7 +422,7 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
>  
>  FILES
>  -----
> -When initializing submodules, a .gitmodules file in the top-level directory
> +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 `$GIT_DIR/config`. The key
>  to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
>
> --
> https://github.com/git/git/pull/377

Re: [PATCH/FINAL] Documentation/git-submodule: cleanup

[Stefan Beller]

On Thu, Jun 22, 2017 at 12:07 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> The "add" section for 'git-submodule' is redundant in
>> its description and the short synopsis line. Fix it.
>>
>> Remove the redundant mentioning of the 'repository' argument
>> being mandatory.
>>
>> The text is hard to read because of back-references, so remove
>> those.
>>
>> Replace the word "humanish" by "canonical" as that conveys better
>> what we do to guess the path.
>>
>> While at it, quote all occurrences of '.gitmodules' as that is an
>> important file in the submodule context, also link to it on its
>> first mention.
>>
>> Helped-by: Stefan Beller <sbeller@google.com>
>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>> ---
>
> Stefan, do you want to add a Reviewed-by: to this one?  I've scanned
> it over and overall it looked OK (iow I didn't find anything worth
> complaining about).

I found it a pleasant read, thanks.

As all occurrences of '.gitmodules' are touched, I suspect we will run into
a conflict with sb/submodule-doc, such that I will rebase on top of this.

Thanks,
Stefan