Re: [PATCH] Documentation/git.txt: command re-classification

From: Nicolas Pitre <nico@cam.org>
Date: Jan 19, 2007, 22:44 UTC
Message-ID: <Pine.LNX.4.64.0701191729060.3011@xanadu.home>
In-Reply-To: <7vbqkufyhy.fsf@assigned-by-dhcp.cox.net>

On Fri, 19 Jan 2007, Junio C Hamano wrote:

Show 12 quoted lines

> Nicolas Pitre <nico@cam.org> writes:
> 
> > OK.  But I think the following are still misclassified:
> >
> >   git-rev-parse
> >   git-runstatus
> >   git-fsck-objects
> 
> Thanks for proofreading.  runstatus should be a pure helper.  I
> am not sure what rev-parse and fsck-objects are, but they are
> not primary porcelain.  rev-parse could sit next to rev-list and
> fsck-objects, I guess.

I don't think fsck-objects is really plumbing though. I'd tag it as ancillaryinterrogators.

Also, having:

   git-am(1)
          Apply a series of patches from a mailbox.

   git-applymbox(1)
          Apply a series of patches in a mailbox.

looks a bit weird. Why two commands with almost the same description? Maybe one of them could be relegated to ancillary? Or even both of them to foreignscminterface?

Is git-show-branch really a primary command?

Then what about moving one of annotate or blame to the main section?

Show 14 quoted lines

> >> +The interface (input, output, set of options and the semantics) 
> >> +to these low-level commands are meant to be a lot more stable 
> >> +than Porcelain level commands, because these commands are 
> >> +primarily for scripted use.  To put it another way, the +interface 
> >> to Plumbing commands are subject to change in order to +improve the 
> >> end user experience.
> >
> > I think the "to put it another way" sentence is a bit confusing here.
> 
> I agree.  What I wanted to say was the interface to plumbing is
> sacred and we will not lightly change it without a very good
> reason, while Porcelains are more or less "for breaking".
> 
> Better wording is certainly appreciated.

I'd just drop the "to put it another way" entirely.

Nicolas