From: Petr Baudis <pasky@suse•cz>
To: Junio C Hamano <gitster@pobox•com>, Heikki Orsila <shdl@zakalwe•fi>
Cc: git@vger•kernel.org
Subject: Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section
Date: Thu, 17 Jul 2008 14:18:13 +0200 [thread overview]
Message-ID: <20080717121813.GC10151@machine.or.cz> (raw)
In-Reply-To: <20080717104124.GE4379@zakalwe.fi> <7vej5tr5kv.fsf@gitster.siamese.dyndns.org>
On Wed, Jul 16, 2008 at 12:29:03PM -0700, Junio C Hamano wrote:
> Petr Baudis <pasky@suse•cz> 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
next prev parent reply other threads:[~2008-07-17 12:19 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-07-15 10:22 [PATCH] Documentation/git-submodule.txt: Add Description section Petr Baudis
2008-07-15 14:06 ` Junio C Hamano
2008-07-15 18:37 ` Heikki Orsila
2008-07-16 18:44 ` [PATCHv2] " Petr Baudis
2008-07-16 19:15 ` Kalle Olavi Niemitalo
2008-07-16 19:29 ` Junio C Hamano
2008-07-17 12:18 ` Petr Baudis [this message]
2008-07-17 12:29 ` [PATCH] Documentation/git-submodule.txt: Further clarify the description Petr Baudis
2008-07-17 13:37 ` Heikki Orsila
2008-07-17 20:24 ` Junio C Hamano
2008-07-18 13:36 ` Petr Baudis
2008-07-18 13:40 ` Petr Baudis
2008-07-17 10:41 ` [PATCHv2] Documentation/git-submodule.txt: Add Description section Heikki Orsila
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20080717121813.GC10151@machine.or.cz \
--to=pasky@suse$(echo .)cz \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=shdl@zakalwe$(echo .)fi \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox