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

From: Philip Oakley <philipoakley@iee.org>
Date: May 10, 2012, 20:30 UTC
Message-ID: <A406C457BFB948FC9843C8F53AD82CDE@PhilipOakley>
In-Reply-To: <20120510185903.GF76400@book.hvoigt.net>

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

Show 56 quoted lines

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