Re: Cleaning up git user-interface warts

Carl Worth [off-list ref] writes:

I'm not the original poster, but I feel the same way about the line
being unclear.

Here's a real-world example from last week.
...
Anyway, when I announced this I also mentioned how easily someone
might generate an entire series of reports for a series of
commits. The command I gave as an example is:

	for rev in $(git rev-list 1.2.6..HEAD); do
	    cairo-perf-diff $rev
	done

I think that's a perfectly legitimate one-liner for users to use, and
it really shows off the easy-scriptability of git. But certainly, no
"new porcelain" author is going to consider rev-list to be porcelain
rather than plumbing, right? So as soon as I start teaching people to
do useful stuff like this, they might have to reach down into the
"scary" git interface.

That is a very fine example, but I do not see why it is a
problem.  I do not think the goal of Porcelain is to make it
totally unnecessary for users to know about the plumbing.

The one-liner is essentially a new Porcelain command that is
useful in the cairo developers' workflow, and implementing it
with a plumbing command makes perfect sense.  The whole point of
git plumbing is to be friendly for scripted use.  If the user
who learns that one-liner from you gets curious why and how that
one-liner works, that would be a good gentle introduction to the
plumbing, but otherwise the user is not forced to know about it.

Also I do not see a problem if some plumbing commands happen to
be also useful by themselves ("[alias] less = -p cat-file -p"
comes to mind for example).

Some plumbing commands may be too deep magic and users do not
have to directly deal with them every day.  Some other plumbing
commands are so low-level and needs combination with others to
be any useful, and it is cumbersome to type the combination
every day.  For the latter kind, we have Porcelain commands that
implement the frequently used combination and the end users do
not have to know about them.

So it is true that by having a rich and usable set of Porcelain,
there is less need for the users to know about all the plumbing
details, but I consider that is a happy consequence.  It does
not have to be the goal of having a good Porcelain to hide the
whole plumbing.

On Thu, Nov 16, 2006 at 11:09:13AM CET, Robin Rosenberg wrote:

torsdag 16 november 2006 04:21 skrev Petr Baudis:

quoted

Another point is, if using _just_ _git_ requires you to learn "all those
git commands too" from git-commit-tree up (yes it does! if you want your
authorship information to be correct), something is wrong.

When/why do I need git-commit-tree? Isn't git-commit enough?

As I said, when you need to find out how to setup your authorship
information. It's documented as deep as on the git-commit-tree level.
BTW, the documentation is another important part of the
plumbing/porcelain separation, it's not only about the list of commands
but also that porcelain documentation should be reasonably
self-contained and not require users to peek at plumbing docs in order
to find out many stuff. It's also a consideration I take when
maintaining Cogito documentation.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:

That is a very fine example, but I do not see why it is a
problem.  I do not think the goal of Porcelain is to make it
totally unnecessary for users to know about the plumbing.

If not, then the promise of the porcelain fails. If cogito offers
"Here are 40 commands so you don't have to learn git's 140" and then
next says "Oh, and you'll still want to learn all those git commands
too", then its existence only makes the "too much stuff to learn"
problem worse, not better.

But I think you agree with me (for now) that fixing the git UI should
not involve creating a new primary command to replace "git".

-Carl

torsdag 16 november 2006 04:21 skrev Petr Baudis:

Another point is, if using _just_ _git_ requires you to learn "all those
git commands too" from git-commit-tree up (yes it does! if you want your
authorship information to be correct), something is wrong.

When/why do I need git-commit-tree? Isn't git-commit enough?

On Wed, Nov 15, 2006 at 11:36:21PM CET, Carl Worth wrote:

On Wed, 15 Nov 2006 13:13:11 -0800, Junio C Hamano wrote:

quoted

That is a very fine example, but I do not see why it is a
problem.  I do not think the goal of Porcelain is to make it
totally unnecessary for users to know about the plumbing.

If not, then the promise of the porcelain fails. If cogito offers
"Here are 40 commands so you don't have to learn git's 140" and then
next says "Oh, and you'll still want to learn all those git commands
too", then its existence only makes the "too much stuff to learn"
problem worse, not better.

I didn't get this argument before either - why do you need to learn "all
those git commands" too? You'll never have to learn "git add" or even
"git commit". If you want to pick specific git commands later (like "git
bisect", which even seeks in a Cogito-compatible way), that's fine, go
ahead! But you by no means have to learn _other_ commands than those you
need. If you want to bisect, you have to learn no other Git commands
than "git bisect".

Another point is, if using _just_ _git_ requires you to learn "all those
git commands too" from git-commit-tree up (yes it does! if you want your
authorship information to be correct), something is wrong.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1