Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Heiko Voigt <hvoigt@hvoigt.net>]

On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote:
> On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:
> > Stefan Beller <sbeller@google.com> writes:
> > On the other hand, I probably would not have felt such a strong
> > "strangeness" if it were described like this:
> >
> >     This command can help you inspect, update, and manage
> >     submodules.
> >
> > I haven't analized it enough to say why it is, but I suspect it has
> > something to do with (my own) perception that "git submodule" is not
> > very essential to do any of these things (i.e. .gitmodules is a very
> > simple text file), but is primarily a helpful wrapper.
> 
> My perception is that the submodule man page similar to the subtree
> man page tries to explain an underlying concept as well. The other man
> pages you quoted don't do that as the concepts are explained elsewhere(?)
> 
> As a side note: In the Gerrit test suite I use the JGit implementation of
> the config command to write out .gitmodules files. So maybe `git submodule`
> can be understood as a specialized form of `git config`.

I do not agree here. That view is too limited. Since in the case of e.g. 'git
submodule add‘ it does not only change the .gitmodules file but adds a gitlink
entry to the index, moves the database into .git/modules, ... .

And even though it is currently not doing much more it might in the
future. E.g. it might make sense to add a 'git submodule gc' command
which allows the user to purge unused submodule databases from the
.git/modules directory.

So I would say it is: "a helper" or "a tool" for submodules. Nothing less
nothing more. But on the other hand the same is true for other porcelain
commands like e.g. 'git commit'. If you take a look at gitcore-tutorial
you could also describe it as a wrapper for write-tree, commit-tree and
update-ref to create a commit. Yet the man page says: "Record changes to
the repository".

So I am not sure where to draw the line between wrapper and essential
command. As a user I would see it as quite essential since for adding a
submodule I would need to remember a couple of things:

  * clone the database into .git/modules
  * create the gitlink file
  * checkout the files to the desired directory
  * add the url to the .gitmodules file

So why not go with Junios first suggestion and lets drop the "This
command can help you..." and say: "Inspect, update and manage
submodules".

Cheers Heiko