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

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

Nicolas Pitre <nico@cam.org> writes:

Show 12 quoted lines

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

I thought about that issue (also annotate vs blame). I'm fine with demoting applymbox to ancillary, perhaps with potential future deprecation in mind (but that would be a separate topic).

annotate is already ancillary and blame also is. Do you want to promote one of them to mainporcelain?

> Is git-show-branch really a primary command?

Ah, I didn't notice that you wanted to move it out of mainporcelain in your patch.

I personally use it quite often while juggling topics, especially since I do not usually work inside X, but I'm fine either way -- ancillaryinterrogators?

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

Ok, then how about this on top of what you saw on the list.

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 9443ab3..4b76d19 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -62,7 +62,7 @@ __DATA__
 git-add                                 mainporcelain
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators
-git-applymbox                           mainporcelain
+git-applymbox                           ancillaryinterrogators
 git-applypatch                          purehelpers
 git-apply                               plumbingmanipulators
 git-archimport                          foreignscminterface
@@ -159,7 +159,7 @@ git-send-pack                           synchingrepositories
 git-shell                               synchelpers
 git-shortlog                            mainporcelain
 git-show                                mainporcelain
-git-show-branch                         mainporcelain
+git-show-branch                         ancillaryinterrogators
 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators
 git-sh-setup                            purehelpers
diff --git a/Documentation/git.txt b/Documentation/git.txt
index ded48b5..9761de3 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -115,9 +115,9 @@ gitlink:git-read-tree[1].
 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.
+primarily for scripted use.  The interface to Porcelain commands
+on the other hand are subject to change in order to improve the
+end user experience.
 
 The following description divides
 the low-level commands into commands that manipulate objects (in