[PATCH] document submdule.$name.update=none option for gitmodules

[PATCH] document submdule.$name.update=none option for gitmodules

[Heiko Voigt]

This option was not yet described in the gitmodules documentation. We
only described it in the 'git submodule' command documentation but
gitmodules is the more natural place to look.

A short reference in the 'git submodule' documentation should be
sufficient since the details can now be found in the documentation to
gitmodules.

Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
---
 Documentation/git-submodule.txt |    7 ++-----
 Documentation/gitmodules.txt    |    5 ++++-
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index c243ee5..c83a856 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -140,7 +140,8 @@ update::
 	checkout the commit specified in the index of the containing repository.
 	This will make the submodules HEAD be detached unless `--rebase` or
 	`--merge` is specified or the key `submodule.$name.update` is set to
-	`rebase`, `merge` or `none`.
+	`rebase`, `merge` or `none`. `none` can be overriden by specifying
+	`--checkout`.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -148,10 +149,6 @@ submodule with the `--init` option.
 +
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
-+
-If the configuration key `submodule.$name.update` is set to `none` the
-submodule with name `$name` will not be updated by default. This can be
-overriden by adding `--checkout` to the command.
 
 summary::
 	Show commit summary between the given commit (defaults to HEAD) and
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 4e1fd52..4effd78 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -41,8 +41,11 @@ submodule.<name>.update::
 	the commit specified in the superproject. If 'merge', the commit
 	specified in the superproject will be merged into the current branch
 	in the submodule.
+	If 'none', the submodule with name `$name` will not be updated
+	by default.
+
 	This config option is overridden if 'git submodule update' is given
-	the '--merge' or '--rebase' options.
+	the '--merge', '--rebase' or '--checkout' options.
 
 submodule.<name>.fetchRecurseSubmodules::
 	This option can be used to control recursive fetching of this
-- 
1.7.10.rc2.31.gd8c60

Re: [PATCH] document submdule.$name.update=none option for gitmodules

[Philip Oakley]

From: "Heiko Voigt" <hvoigt@hvoigt.net> Sent: Thursday, May 10, 2012 7:59 PM
Subject: [PATCH] document submdule.$name.update=none option for gitmodules


> This option was not yet described in the gitmodules documentation. We
> only described it in the 'git submodule' command documentation but
> gitmodules is the more natural place to look.

The gitmodules documentation is only more natural if we tell (link) the reader early in the submodule documentation. A link to 
gitmodules should be provided in the third paragraph of Description where the .gitmodules is introduced.

Currently the gitmodules link is the last thing mentioned (i.e. 8 PgDn's for me).

>
> A short reference in the 'git submodule' documentation should be
> sufficient since the details can now be found in the documentation to
> gitmodules.
>
> Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
> ---
> Documentation/git-submodule.txt |    7 ++-----
> Documentation/gitmodules.txt    |    5 ++++-
> 2 files changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index c243ee5..c83a856 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -140,7 +140,8 @@ update::
>  checkout the commit specified in the index of the containing repository.
>  This will make the submodules HEAD be detached unless `--rebase` or
>  `--merge` is specified or the key `submodule.$name.update` is set to
> - `rebase`, `merge` or `none`.
> + `rebase`, `merge` or `none`. `none` can be overriden by specifying
> + `--checkout`.
> +
> If the submodule is not yet initialized, and you just want to use the
> setting as stored in .gitmodules, you can automatically initialize the
> @@ -148,10 +149,6 @@ submodule with the `--init` option.
> +
> If `--recursive` is specified, this command will recurse into the
> registered submodules, and update any nested submodules within.
> -+
> -If the configuration key `submodule.$name.update` is set to `none` the
> -submodule with name `$name` will not be updated by default. This can be
> -overriden by adding `--checkout` to the command.
>
> summary::
>  Show commit summary between the given commit (defaults to HEAD) and
> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
> index 4e1fd52..4effd78 100644
> --- a/Documentation/gitmodules.txt
> +++ b/Documentation/gitmodules.txt
> @@ -41,8 +41,11 @@ submodule.<name>.update::
>  the commit specified in the superproject. If 'merge', the commit
>  specified in the superproject will be merged into the current branch
>  in the submodule.
> + If 'none', the submodule with name `$name` will not be updated
> + by default.
> +
>  This config option is overridden if 'git submodule update' is given
> - the '--merge' or '--rebase' options.
> + the '--merge', '--rebase' or '--checkout' options.
>
> submodule.<name>.fetchRecurseSubmodules::
>  This option can be used to control recursive fetching of this
> -- 
> 1.7.10.rc2.31.gd8c60
>

[PATCH] link to gitmodules page at the beginning of git-submodule documentation

[Heiko Voigt]

This way the user does not have to scroll down to the bottom to find
it.

Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
---
On Thu, May 10, 2012 at 09:30:12PM +0100, Philip Oakley wrote:
> From: "Heiko Voigt" <hvoigt@hvoigt.net> Sent: Thursday, May 10, 2012 7:59 PM
>> This option was not yet described in the gitmodules documentation. We
>> only described it in the 'git submodule' command documentation but
>> gitmodules is the more natural place to look.
>
> The gitmodules documentation is only more natural if we tell (link) the 
> reader early in the submodule documentation. A link to gitmodules should 
> be provided in the third paragraph of Description where the .gitmodules 
> is introduced.
>
> Currently the gitmodules link is the last thing mentioned (i.e. 8 PgDn's for me).

The gitmodules documentation page describes all the options you can use
there so its by definition more natural. Yes I can see that a link to
gitmodules page could be provided earlier but thats a completely
different topic independent from my previous patch. Instead of
complaining how about providing a patch next time?

Anyway here we go...

 Documentation/git-submodule.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index c83a856..9e488c0 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -43,9 +43,9 @@ if you choose to go that route.
 Submodules are composed from a so-called `gitlink` tree entry
 in the main repository that refers to a particular commit object
 within the inner repository that is completely separate.
-A record in the `.gitmodules` file at the root of the source
-tree assigns a logical name to the submodule and describes
-the default URL the submodule shall be cloned from.
+A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
+root of the source tree assigns a logical name to the submodule and
+describes the default URL the submodule shall be cloned from.
 The logical name can be used for overriding this URL within your
 local repository configuration (see 'submodule init').
 
-- 
1.7.10.1.488.ga84c0c8

Re: [PATCH] link to gitmodules page at the beginning of git-submoduledocumentation

[Philip Oakley]

From: "Heiko Voigt" <hvoigt@hvoigt.net> Sent: Monday, May 14, 2012 6:32 PM
> This way the user does not have to scroll down to the bottom to find
> it.
>
> Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net>
> ---
> On Thu, May 10, 2012 at 09:30:12PM +0100, Philip Oakley wrote:
>> From: "Heiko Voigt" <hvoigt@hvoigt.net> Sent: Thursday, May 10, 2012 7:59 PM
>>> This option was not yet described in the gitmodules documentation. We
>>> only described it in the 'git submodule' command documentation but
>>> gitmodules is the more natural place to look.
>>
>> The gitmodules documentation is only more natural if we tell (link) the
>> reader early in the submodule documentation. A link to gitmodules should
>> be provided in the third paragraph of Description where the .gitmodules
>> is introduced.
>>
>> Currently the gitmodules link is the last thing mentioned (i.e. 8 PgDn's for me).
>
> The gitmodules documentation page describes all the options you can use
> there so its by definition more natural. Yes I can see that a link to
> gitmodules page could be provided earlier but thats a completely
> different topic independent from my previous patch. Instead of
> complaining how about providing a patch next time?

My apologies, I was thinking I was avoiding a clash of patches on a common file, rather than seeing the independance you noted. 
Thank you for the patch.

>
> Anyway here we go...
>
> Documentation/git-submodule.txt | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index c83a856..9e488c0 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -43,9 +43,9 @@ if you choose to go that route.
> Submodules are composed from a so-called `gitlink` tree entry
> in the main repository that refers to a particular commit object
> within the inner repository that is completely separate.
> -A record in the `.gitmodules` file at the root of the source
> -tree assigns a logical name to the submodule and describes
> -the default URL the submodule shall be cloned from.
> +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
> +root of the source tree assigns a logical name to the submodule and
> +describes the default URL the submodule shall be cloned from.
> The logical name can be used for overriding this URL within your
> local repository configuration (see 'submodule init').
>
> -- 
> 1.7.10.1.488.ga84c0c8
>
>
>
> -----