Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description

From: Petr Baudis <pasky@suse.cz>
Date: Jul 18, 2008, 13:36 UTC
Message-ID: <20080718133644.GQ10151@machine.or.cz>
In-Reply-To: <7v4p6ofedl.fsf@gitster.siamese.dyndns.org>

On Thu, Jul 17, 2008 at 01:24:22PM -0700, Junio C Hamano wrote:

> Your lines are getting overlong to be easily quoted and commented...

I will watch for that.

Show 19 quoted lines

> Petr Baudis <pasky@suse.cz> writes:
> > +....  In case you want to merge the project
> > +histories, possibly make local modifications within the tree, but also do not
> > +mind that your repository will bulk up with all the contents of the other
> > +project, consider adding a remote for the other project and using the 'subtree'
> > +merge strategy instead of setting up a submodule.
> 
> I'd suggest rephrasing "do not mind" to something a lot less nagative.
> The user decides to merge because both histories *are* relevant and at
> that point there is no _minding_ anymore.  If you want to have them, you
> not only "do not mind to have" them but you positively "want" them.
> 
> On the other hand, a situation where you would want to use submodules is
> when not necessarily all users of the superproject would want to have all
> submodules cloned nor checked out.  This needs to be stressed with equal
> weight as the above sentence in this "contrasting merged histories and
> submodules" paragraph.  With that explained clearly upfront, it would
> become easier for the readers to understand why you can choose not to even
> update nor fetch submodules you are not interested in.

You are right. I have tried to reword the sentence to fix these issues.

Show 6 quoted lines

> > +Submodules are composed from a special kind of tree entry (so-called `gitlink`)
> > +in the main repository that refers to a particular commit object within
> 
> Do we have to say "special"?  Is a gitlink any more special than blob and
> tree entries are?  It tends to be rarer, it came later, but I do not think
> there is anything special from the end user's point of view.

Also the parenthesis look ugly, so I have reworded this to a simpler formulation.

Show 6 quoted lines

> >  checked out and at appropriate revision in your working tree. You can inspect
> >  the current status of your submodules using the 'submodule' subcommand and get
> > +an overview of the changes 'update' would perform using the 'summary'
> > +subcommand.
> 
> Sorry, cannot parse the last three lines...

The mention of 'update' is confusing, and it was overally imprecise. (I think that in general, the summary/status distinction was not a wise UI decision.)

-- 
				Petr "Pasky" Baudis
As in certain cults it is possible to kill a process if you know
its true name.  -- Ken Thompson and Dennis M. Ritchie