* [PATCH/RFC] Cleanup Documentation @ 2017-06-19 3:05 Kaartic Sivaraam 2017-06-19 5:24 ` Junio C Hamano 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-19 3:05 UTC (permalink / raw) To: gitster; +Cc: git, 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-19 3:05 [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam @ 2017-06-19 5:24 ` Junio C Hamano 2017-06-19 5:50 ` Stefan Beller 0 siblings, 1 reply; 15+ messages in thread From: Junio C Hamano @ 2017-06-19 5:24 UTC (permalink / raw) To: Stefan Beller; +Cc: git, Kaartic Sivaraam 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-19 5:24 ` Junio C Hamano @ 2017-06-19 5:50 ` Stefan Beller 2017-06-19 17:33 ` Kaartic Sivaraam 0 siblings, 1 reply; 15+ messages in thread From: Stefan Beller @ 2017-06-19 5:50 UTC (permalink / raw) To: Junio C Hamano, mlevedahl; +Cc: git@vger.kernel.org, Kaartic Sivaraam 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-19 5:50 ` Stefan Beller @ 2017-06-19 17:33 ` Kaartic Sivaraam 2017-06-19 17:54 ` Stefan Beller 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-19 17:33 UTC (permalink / raw) To: Stefan Beller, Junio C Hamano, mlevedahl; +Cc: git@vger.kernel.org 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> ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-19 17:33 ` Kaartic Sivaraam @ 2017-06-19 17:54 ` Stefan Beller 2017-06-20 3:12 ` Kaartic Sivaraam 0 siblings, 1 reply; 15+ messages in thread From: Stefan Beller @ 2017-06-19 17:54 UTC (permalink / raw) To: Kaartic Sivaraam; +Cc: Junio C Hamano, mlevedahl, git@vger.kernel.org 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH/RFC] Cleanup Documentation 2017-06-19 17:54 ` Stefan Beller @ 2017-06-20 3:12 ` Kaartic Sivaraam 2017-06-20 16:57 ` Stefan Beller 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-20 3:12 UTC (permalink / raw) To: sbeller; +Cc: gitster, git, 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-20 3:12 ` Kaartic Sivaraam @ 2017-06-20 16:57 ` Stefan Beller 2017-06-20 17:05 ` Stefan Beller 2017-06-20 18:27 ` [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam 0 siblings, 2 replies; 15+ messages in thread From: Stefan Beller @ 2017-06-20 16:57 UTC (permalink / raw) To: Kaartic Sivaraam; +Cc: Junio C Hamano, git@vger.kernel.org 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-20 16:57 ` Stefan Beller @ 2017-06-20 17:05 ` Stefan Beller 2017-06-21 3:02 ` [PATCH/FINALRFC] Documentation/git-submodule: cleanup Kaartic Sivaraam 2017-06-20 18:27 ` [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam 1 sibling, 1 reply; 15+ messages in thread From: Stefan Beller @ 2017-06-20 17:05 UTC (permalink / raw) To: Kaartic Sivaraam; +Cc: Junio C Hamano, git@vger.kernel.org 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) ^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH/FINALRFC] Documentation/git-submodule: cleanup 2017-06-20 17:05 ` Stefan Beller @ 2017-06-21 3:02 ` Kaartic Sivaraam 2017-06-21 16:11 ` Junio C Hamano 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-21 3:02 UTC (permalink / raw) To: Stefan Beller; +Cc: Junio C Hamano, git@vger.kernel.org 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup 2017-06-21 3:02 ` [PATCH/FINALRFC] Documentation/git-submodule: cleanup Kaartic Sivaraam @ 2017-06-21 16:11 ` Junio C Hamano 2017-06-21 17:41 ` Kaartic Sivaraam 0 siblings, 1 reply; 15+ messages in thread From: Junio C Hamano @ 2017-06-21 16:11 UTC (permalink / raw) To: Kaartic Sivaraam; +Cc: Stefan Beller, git@vger.kernel.org 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? ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/FINALRFC] Documentation/git-submodule: cleanup 2017-06-21 16:11 ` Junio C Hamano @ 2017-06-21 17:41 ` Kaartic Sivaraam 2017-06-22 2:51 ` [PATCH/FINAL] " Kaartic Sivaraam 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-21 17:41 UTC (permalink / raw) To: Junio C Hamano; +Cc: Stefan Beller, git@vger.kernel.org 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> ^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH/FINAL] Documentation/git-submodule: cleanup 2017-06-21 17:41 ` Kaartic Sivaraam @ 2017-06-22 2:51 ` Kaartic Sivaraam 2017-06-22 19:07 ` Junio C Hamano 0 siblings, 1 reply; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-22 2:51 UTC (permalink / raw) To: git 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH/FINAL] Documentation/git-submodule: cleanup 2017-06-22 2:51 ` [PATCH/FINAL] " Kaartic Sivaraam @ 2017-06-22 19:07 ` Junio C Hamano 2017-06-22 19:13 ` Stefan Beller 0 siblings, 1 reply; 15+ messages in thread From: Junio C Hamano @ 2017-06-22 19:07 UTC (permalink / raw) To: Stefan Beller; +Cc: git, Kaartic Sivaraam 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/FINAL] Documentation/git-submodule: cleanup 2017-06-22 19:07 ` Junio C Hamano @ 2017-06-22 19:13 ` Stefan Beller 0 siblings, 0 replies; 15+ messages in thread From: Stefan Beller @ 2017-06-22 19:13 UTC (permalink / raw) To: Junio C Hamano; +Cc: git@vger.kernel.org, Kaartic Sivaraam 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH/RFC] Cleanup Documentation 2017-06-20 16:57 ` Stefan Beller 2017-06-20 17:05 ` Stefan Beller @ 2017-06-20 18:27 ` Kaartic Sivaraam 1 sibling, 0 replies; 15+ messages in thread From: Kaartic Sivaraam @ 2017-06-20 18:27 UTC (permalink / raw) To: Stefan Beller; +Cc: Junio C Hamano, git@vger.kernel.org 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> ^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2017-06-22 19:13 UTC | newest] Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-06-19 3:05 [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam 2017-06-19 5:24 ` Junio C Hamano 2017-06-19 5:50 ` Stefan Beller 2017-06-19 17:33 ` Kaartic Sivaraam 2017-06-19 17:54 ` Stefan Beller 2017-06-20 3:12 ` Kaartic Sivaraam 2017-06-20 16:57 ` Stefan Beller 2017-06-20 17:05 ` Stefan Beller 2017-06-21 3:02 ` [PATCH/FINALRFC] Documentation/git-submodule: cleanup Kaartic Sivaraam 2017-06-21 16:11 ` Junio C Hamano 2017-06-21 17:41 ` Kaartic Sivaraam 2017-06-22 2:51 ` [PATCH/FINAL] " Kaartic Sivaraam 2017-06-22 19:07 ` Junio C Hamano 2017-06-22 19:13 ` Stefan Beller 2017-06-20 18:27 ` [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).