On Wed, Jul 16, 2008 at 12:29:03PM -0700, Junio C Hamano wrote: > Petr Baudis <pasky@xxxxxxx> writes: > > > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt > > index 76702a0..87c4ece 100644 > > --- a/Documentation/git-submodule.txt > > +++ b/Documentation/git-submodule.txt > > @@ -16,6 +16,28 @@ SYNOPSIS > > 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] > > > > > > +DESCRIPTION > > +----------- > > +Submodules are a special kind of tree entries which refer to a particular tree > > +in another repository (living at a given URL). ... > > In the documentation, "tree" has a specific meaning. Perhaps "a > particular tree state" is a better wording than another alternative "a > particular commit", because you mention "the exact revision" in the > following sentence. The two sentences are now highly redundant, so... > I'd suggest dropping " (living at a given URL)" from here, though. ...actually, in the end I have completely rewritten this yet again. The description was too low-level (and kind of in fact explained gitlinks instead of submodules), while we should carefully explain the high-level concept of submodules first, only then talk about tree entries. > > ... The tree entry describes > > +the existence of a submodule with the given name and the exact revision that > > +should be used, while the location of the repository is described in the > > +`/.gitmodules` file. > > Strictly speaking, ".gitmodules" merely gives a hint to be used by > "submodule init", the canonical location from which the repository is > expected to be cloned. I do not think this overview needs to go into such > a detail. The description of "init" subcommand might need clarification, > though. I believe we should mention it. The users *will* see this file e.g. during submodule merges, as well as in git status output when manipulating submodules. On Thu, Jul 17, 2008 at 01:41:24PM +0300, Heikki Orsila wrote: > On Wed, Jul 16, 2008 at 08:44:12PM +0200, Petr Baudis wrote: > > I have adjusted the description a bit; however, I believe mentioning > > remotes in > > the description would only raise the danger of confusion - I emphasized the > > level of separation, though. > > I think not doing a comparison actually creates confusion. My immediate > thought about submodules was "how does this differ from remotes? why do > submodules exist rather than just remotes?" Ok, now I realize this is a good point, and it's a nice chance to give a plug for the subtree merge strategy as an alternative. ;-) -- Petr "Pasky" Baudis GNU, n. An animal of South Africa, which in its domesticated state resembles a horse, a buffalo and a stag. In its wild condition it is something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce -- 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
