Subject: Re: [PATCH 1/2] Unification of user message strings

From: Jakub Narebski <[email-masked]>
Date: Tue, 20 Mar 2012 05:01:05 -0700 (PDT)

Vincent van Ravesteijn <[email-masked]> writes:

> > I had a vague impression that plumbing messages tend to be lowercase.  If
> > it is not be too much trouble, it might be interesting to redo the numbers
> > divided into the plumbing and Porcelain messages. Perhaps these "50%"
> > folks updated both plumbing and Porcelain. Another possibility is that
> > they tried to follow the local convention when they added a new one, or
> > reworded an existing one.
> >
> > If we would be rewording, we would only be doing the Porcelain messages,
> > so I am OK with either way.
> 
> It seems that the terms "Porcelain" and "plumbing" seems to be mixed
> up somewhere.
> 
>  From 'git help status': "The porcelain format is similar to the short
> format, but is guaranteed not to change in a backwards-incompatible
> way between git versions or based on user configuration. This makes it
> ideal for parsing by scripts".

The '--porcelain' option means "intended *for* parsing by porcelain",
not that it is 'porcelain' output.
 
>  From 'http://progit.org/book/ch9-1.html': "....it has a bunch of
> verbs that do low-level work and were designed to be chained together
> UNIX style or called from scripts. These commands are generally
> referred to as 'plumbing' commands, and the more user-friendly
> commands are called 'porcelain' commands."

Mnemonics: "plumbing" are hidden 'guts' of git (the engine / backend
part).

> It feels like 'porcelain' means: "be careful, things break easily";
> and 'plumbing' means: "use all the force you want to get it into (a
> user-friendly) shape".
> 
> Second, to me it is not totally clear which strings are plumbing and
> which ones are porcelain. Is there a general rule to tell ? The
> command-list file says what the general intention of a command is, but
> often it's both plumbing as porcelain.

"Porcelain" commands are those that are facing user (as is "porcelain"
in armature), so they might be changed to make it more user friendly.
 
"Plumbing" command output is to be consumed by other commands and
scripts, so it must be 'cast in stone' and cannot be changed.  It is
meant to be easily machine-parseable, and not to be user friendly.

> Can anyone help me out here ?

HTH
-- 
Jakub Narebski