From: P Baker <me@retrodict.com>
To: git@vger.kernel.org
Subject: [PATCH 1/2] Clarify the gitmodules and submodules docs
Date: Wed, 8 Apr 2009 03:04:46 -0400 [thread overview]
Message-ID: <526944450904080004r1249d1b8j4a44472d72502b9c@mail.gmail.com> (raw)
In-Reply-To: <1239172816-38966-1-git-send-email-pbaker@retrodict.com>
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
next parent reply other threads:[~2009-04-08 7:06 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <1239172816-38966-1-git-send-email-pbaker@retrodict.com>
2009-04-08 7:04 ` P Baker [this message]
2009-04-08 7:16 ` [PATCH 1/2] Clarify the gitmodules and submodules docs Junio C Hamano
2009-04-08 15:33 pbaker
2009-04-08 15:45 ` P Baker
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=526944450904080004r1249d1b8j4a44472d72502b9c@mail.gmail.com \
--to=me@retrodict.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).