Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section

On Wed, Jul 16, 2008 at 12:29:03PM -0700, Junio C Hamano wrote:

Petr Baudis [off-list ref] writes:

quoted

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.

quoted

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

quoted

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