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

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

[pbaker]

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

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

[P Baker]

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

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

[P Baker]

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

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

[Junio C Hamano]

I think the new description is good, and the message claims to be sent by
send-email, but I am seeing a funny whitespace damage everywhere in your
patch.

 * Signed-off-by: and the three-dash lines have a leading SP

 * The first line of diffstat is indented by one SP as expected; the
   second line has one extra SP at the beginning.

 * everything after that has one extra SP at the beginning.  Also the hunk
   header for the first hunk is linewrapped.

Very curious.  I could just hand munge the patch if I wanted to, but I'd
rather not.  As you are in "GSoC preparation", I expect to receive
patches, perhaps tons of them, from you in the future, and I'd want to see
easier procedural wrinkles straightened out first.  That will allow us to
concentrate on the substance when "the real thing" starts.

    Added some explanation to the docs to clear up some confusing parts of
    git-submodules that appeared frequently on the mailing list.

We tend to say "Add some explanation..." here.  Think of it as your giving
an order to _me_, "cause this to happen", by accepting and applying your
patch.