Re: [PATCH 1/2] Clarify the gitmodules and submodules docs

[P Baker <me@retrodict.com>]

Whoops. Sorry for the spam, trying to fix git-send-email whitespace
errors as per Junio's request. I apologize.

P Baker

On 4/8/09, pbaker <pbaker@retrodict.com> wrote:
> Added some explanation to the docs to clear up some confusing parts of git-submodules that appeared frequently on the mailing list.
>
>  Signed-off-by: pbaker <pbaker@retrodict.com>
>  ---
>
>  As I dug into the reasoning and structure of git-submodule as part of GSoC preparation, I also ran across frequently asked questions on the mailing list. From this background, I added some explanation to the docs to  clear up some confusing parts of git-submodules.
>
>  - pbaker
>
>  Documentation/git-submodule.txt |    9 ++++++---
>   Documentation/gitmodules.txt    |    8 +++++++-
>   2 files changed, 13 insertions(+), 4 deletions(-)
>
>  diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
>  index 3b8df44..1ca8184 100644
>  --- a/Documentation/git-submodule.txt
>  +++ b/Documentation/git-submodule.txt
>  @@ -50,9 +50,12 @@ This command will manage the tree entries and contents of the
>   gitmodules file for you, as well as inspect the status of your
>   submodules and update them.
>   When adding a new submodule to the tree, the 'add' subcommand
>  -is to be used.  However, when pulling a tree containing submodules,
>  -these will not be checked out by default;
>  -the 'init' and 'update' subcommands will maintain submodules
>  +is to be used. This creates a record in the gitmodules file for each
>  +submodule. When the file is committed and pulled by others it serves as an
>  +in-tree reference for where to obtain the submodule.
>  +
>  +When pulling a tree containing submodules, these will not be checked out by
>  +default; the 'init' and 'update' subcommands will maintain submodules
>   checked out and at appropriate revision in your working tree.
>   You can briefly inspect the up-to-date status of your submodules
>   using the 'status' subcommand and get a detailed overview of the
>  diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
>  index d1a17e2..8f03310 100644
>  --- a/Documentation/gitmodules.txt
>  +++ b/Documentation/gitmodules.txt
>  @@ -15,7 +15,13 @@ DESCRIPTION
>
>   The `.gitmodules` file, located in the top-level directory of a git
>   working tree, is a text file with a syntax matching the requirements
>  -of linkgit:git-config[1].
>  +of linkgit:git-config[1]. As this file is managed by Git, it tracks the
>  +records of a project's submodules. Information stored in this file is used
>  +as a hint to prime the authoritative version of the record stored in the
>  +project configuration file. User specific record changes (e.g. to account
>  +for differences in submodule URLs due to networking situations) should be
>  +made to the configuration file, while record changes to be propagated (e.g.
>  +due to a relocation of the submodule source) should be made to this file.
>
>   The file contains one subsection per submodule, and the subsection value
>   is the name of the submodule. Each submodule section also contains the
>
> --
>  1.6.2.1.316.gedbc2
>
>