Re: [PATCH] submodule documentation: Reorder introductory paragraphs

From: Heiko Voigt <hvoigt@hvoigt.net>
Date: May 26, 2015, 21:58 UTC
Message-ID: <20150526215809.GA922@book.hvoigt.net>
In-Reply-To: <CAGZ79kZHRRqKpSmnEfd7-UOL9QrPOhQYt7wsfaqGVTZkHc+mhQ@mail.gmail.com>

On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote:

Show 20 quoted lines

> 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