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

From: Junio C Hamano <junkio@cox.net>
Date: Jan 19, 2007, 22:22 UTC
Message-ID: <7vbqkufyhy.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <Pine.LNX.4.64.0701191437450.3011@xanadu.home>

Nicolas Pitre <nico@cam.org> writes:

Show 5 quoted lines

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

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