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@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> > --- > > 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 > > -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html