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

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.

Petr Baudis [off-list ref] writes:

quoted

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

quoted

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

quoted

 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