From: Heiko Voigt <hvoigt@hvoigt.net>
To: Stefan Beller <sbeller@google.com>
Cc: Junio C Hamano <gitster@pobox.com>,
Philip Oakley <philipoakley@iee.org>,
Jonathan Nieder <jrnieder@gmail.com>,
"git@vger.kernel.org" <git@vger.kernel.org>
Subject: Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Date: Tue, 26 May 2015 23:58:09 +0200 [thread overview]
Message-ID: <20150526215809.GA922@book.hvoigt.net> (raw)
In-Reply-To: <CAGZ79kZHRRqKpSmnEfd7-UOL9QrPOhQYt7wsfaqGVTZkHc+mhQ@mail.gmail.com>
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
next prev parent reply other threads:[~2015-05-26 21:58 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-05-22 19:38 [PATCH] submodule documentation: Reorder introductory paragraphs Stefan Beller
2015-05-22 21:18 ` Philip Oakley
2015-05-25 22:00 ` Junio C Hamano
2015-05-26 17:53 ` Stefan Beller
2015-05-26 21:58 ` Heiko Voigt [this message]
-- strict thread matches above, loose matches on Subject: below --
2015-05-20 23:11 Stefan Beller
2015-05-21 13:04 ` Heiko Voigt
2015-05-21 17:24 ` Junio C Hamano
2015-05-21 17:43 ` Stefan Beller
2015-05-21 20:03 ` Philip Oakley
2015-05-21 22:08 ` Stefan Beller
2015-05-22 6:59 ` Philip Oakley
2015-05-22 14:36 ` Junio C Hamano
2015-05-22 17:05 ` Stefan Beller
2015-05-22 17:26 ` Junio C Hamano
2015-05-22 17:35 ` Philip Oakley
2015-05-22 17:51 ` Stefan Beller
2015-05-22 19:47 ` Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20150526215809.GA922@book.hvoigt.net \
--to=hvoigt@hvoigt.net \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=philipoakley@iee.org \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).