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

[Junio C Hamano <gitster@pobox.com>]

Petr Baudis <pasky@suse.cz> writes:

> This patch rewrites the general description yet again, first clarifying
> the high-level concept, mentioning the difference to remotes and using
> the subtree merge strategy, then getting to the details about tree
> entries and .gitmodules file.
>
> The patch also makes few smallar grammar fixups of the rest of the
> description and clarifies how does 'init' relate to 'update --init'.
>
> Cc: Heikki Orsila <shdl@zakalwe.fi>
> Signed-off-by: Petr Baudis <pasky@suse.cz>
> ---
>
>  Documentation/git-submodule.txt |   39 +++++++++++++++++++++++++++------------
>  1 files changed, 27 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index bb4e6fb..01d0d91 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -18,24 +18,35 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> +Submodules allow foreign repositories to be embedded within a dedicated
> +subdirectory of the source tree, always pointed at a particular commit.
> +They are not to be confused with remotes, which are meant mainly for branches
> +of the same project; submodules are meant for different projects you would like

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

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

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

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