Re: Considering teaching plumbing to users harmful

"Avery Pennarun" [off-list ref] writes:

svn avoids these excess merges by default, albeit because it puts your
working copy at risk every time you do "svn update".

By default?  As if it has other mode of operation.

Of course if you do not allow any commits in between to make the history
truly forked, you won't see merge commits.  It is like saying that you
like your broken keyboard whose SHIFT key does not work because you think
capital letters look ugly and your keyboard protects you from typing them
by accident.

Is that an improvement?

I won't waste my time further on the apples and rotten oranges comparison,
but you should perhaps listen to Linus's talk where he talks about why it
sucks that SVN/CVS _encourage_ you to keep your local changes uncommitted
for several weeks.

quoted

 You can skip merges with "git log --no-merges", just in case you didn't
 know.

Perhaps this is mostly a user education or documentation issue.  I
know about --no-merges, but it's unclear that this is really a safe
thing to use, particularly if some of your merges have conflicts.
Leaving them out leaves out an important part of history.  Do you use
this option yourself?

Very rarely.  When I run "git shortlog" for summary, it often is handy,
but otherwise no.

On 7/16/08, Junio C Hamano [off-list ref] wrote:

"Avery Pennarun" [off-list ref] writes:

quoted

svn avoids these excess merges by default, albeit because it puts your

 > working copy at risk every time you do "svn update".

By default?  As if it has other mode of operation.

 Of course if you do not allow any commits in between to make the history
 truly forked, you won't see merge commits.  It is like saying that you
 like your broken keyboard whose SHIFT key does not work because you think
 capital letters look ugly and your keyboard protects you from typing them
 by accident.

 Is that an improvement?

 I won't waste my time further on the apples and rotten oranges comparison,

I find it interesting how git usability discussions tend to go.  It
usually starts out by someone saying, "Look, git really isn't that
hard to learn, just do it like this..." and then someone says, "But
actually, that's still really complicated.  Everyone thinks xxx other
VCS is easier to learn.  Here's how they do it..." And then someone
says, "Yeah, but xxx VCS sucks!" and that somehow makes it okay that
git is empirically harder to learn than xxx VCS, as anyone can see by
browsing the web.

svn is fundamentally broken, but just because they did *some* things
wrong doesn't mean they did *everything* wrong.  You can learn lessons
even from your inferiors.

Have fun,

Avery

On Wed, Jul 16, 2008 at 03:29:39PM -0400, Avery Pennarun wrote:

I find it interesting how git usability discussions tend to go.  It
usually starts out by someone saying, "Look, git really isn't that
hard to learn, just do it like this..." and then someone says, "But
actually, that's still really complicated.  Everyone thinks xxx other
VCS is easier to learn.  Here's how they do it..." 

Everyone thinks so? Somehow, I don't, and there are people who think
that Git is easily to learn if you teach it properly.

And then someone
says, "Yeah, but xxx VCS sucks!" and that somehow makes it okay that
git is empirically harder to learn than xxx VCS, as anyone can see by
browsing the web.

Browsing the web is not an empirical study.  And if you say harder, you
should specify to whom. To those who already know xxx VCS, naturally
anything new or different than what you got used to will be difficult
at the beginning. Naturally, it is easier to learn something if there
are more books and articles about it, or just there are more people who
can answer on any your questions. But with everything else being equal,
do you really believe that SVN or CVS is easier to use than Git if we
speak about learning comparable functionality? What is your argument
for that? "svn update"? Well, it is a sure way to make mess in your
working directoy. So, your argument does not sound very convincing.

Dmitry

Hi,

On Wed, 16 Jul 2008, Avery Pennarun wrote:

I find it interesting how git usability discussions tend to go.

I find it not interesting at all, even slightly annoying, that I cannot 
seem to start a perfectly valid discussion about advocating porcelain, and 
trying to even avoid mentioning plumbing in user-visible documentation, 
without somebody highjacking the thread to talk about svn.

I am disinterested in svn.  So disinterested that I do not even want to 
read about it.  What we could learn from svn, we did, positive and 
negative lessons, now there is nothing more to be seen here, please move 
along.

So can those people who have something to say about _my_ subject of 
discussion please speak up?  I think this issue has not been discussed 
properly.

Thanks.
Dscho

On Thu, Jul 17, 2008 at 12:28:27AM +0200, Johannes Schindelin wrote:

Hi,

On Wed, 16 Jul 2008, Avery Pennarun wrote:

quoted

I find it interesting how git usability discussions tend to go.

I find it not interesting at all, even slightly annoying, that I cannot 
seem to start a perfectly valid discussion about advocating porcelain, and 
trying to even avoid mentioning plumbing in user-visible documentation, 
without somebody highjacking the thread to talk about svn.

I've already said I agree with you, but maybe it would be helpful if
you focused the discussion a little more with a concrete suggestion
about how we could improve the user-visible documentation.  For
example, it is already the case that "git help" only shows porcelain
commands, that has been a big step forward.

So a concrete suggestion might be to move the list of plumbing
commands from the top-level git man page to a "git-plumbing" man page.

I'll note that the git user manual is pretty good about avoiding the
use of git plumbing commands.  It's not until Chapter 9, "Low Level
Git Commands" that it start going into the plumbing.  (There are a
couple of mentions of git rev-parse before chapter 9, but that's about
it that I could find).

Was there other git documentation where you think there is too many
references to git plumbing?

						- Ted

Hi,

On Wed, 16 Jul 2008, Theodore Tso wrote:

I've already said I agree with you, but maybe it would be helpful if you 
focused the discussion a little more with a concrete suggestion about 
how we could improve the user-visible documentation.

Well, I was not sure if I was full of shot or not.

So a concrete suggestion might be to move the list of plumbing commands 
from the top-level git man page to a "git-plumbing" man page.

I think that would not help much.

As I replied to Dimitry, I could imagine that moving the plumbing into its 
own manual section would be a way.

I'll note that the git user manual is pretty good about avoiding the use 
of git plumbing commands.  It's not until Chapter 9, "Low Level Git 
Commands" that it start going into the plumbing.  (There are a couple of 
mentions of git rev-parse before chapter 9, but that's about it that I 
could find).

Well, rev-parse is one of my pet peeves this day.  rev-parse is _nothing_ 
but plumbing.

Was there other git documentation where you think there is too many 
references to git plumbing?

Actually, the problem arose with a few "tutorials" on the web, and their 
creators violently arguing for their ways (and me being more and more 
uncertain if they are wrong or me).

And then I saw people on IRC doing the same thing.  Realizing that the 
recipients of the "help" were more confused than before, and just typed 
what was written (they would probably even have typed "rm -rf $HOME") 
because they had given up trying to understand.

Ciao,
Dscho

On Thu, Jul 17, 2008 at 02:25:05AM +0200, Johannes Schindelin wrote:

Well, rev-parse is one of my pet peeves this day.  rev-parse is _nothing_ 
but plumbing.

Actually the the git man page doesn't list rev-parse as plumbing.  :-)

Actually, the problem arose with a few "tutorials" on the web, and their 
creators violently arguing for their ways (and me being more and more 
uncertain if they are wrong or me).

I know you don't like hearing about SVN, but normally the tutorials I
tend to point people to, in addition to the standard official git
tutorial and git's user manual, are these two web pages.  First I tell
people to read first part of:

       http://utsl.gen.nz/talks/git-svn/intro.html

which covers the git "philosophy" very nicely, up to the point where
it starts talking about the "git svn" command, and then I tell them to
go read:

	http://git.or.cz/course/svn.html

There are no git plumbing commands in either of those two web pages,
because most SVN users would run screaming if they were given a
tutorial that talked about git-read-tree or git-commit-tree.  :-)

							- Ted

-----Original Message-----
From: git-owner@vger.kernel.org 
[mailto:git-owner@vger.kernel.org] On Behalf Of Johannes Schindelin
Sent: Wednesday, July 16, 2008 5:28 PM
To: Avery Pennarun
Cc: Junio C Hamano; git@vger.kernel.org
Subject: Re: Considering teaching plumbing to users harmful

So can those people who have something to say about _my_ 
subject of discussion please speak up?  I think this issue 
has not been discussed properly.

I've read this whole thread with great interest as I started learning
and using git a few months ago.  While I agree with you to a degree,
there is a class of "newbies" to git who need more than just the basics
that you outlined.  For instance, I'm in the process of evaluating
VCS's, and DVCS's in particular, to replace CVS at our workplace.
Because of that, I need to get "up to speed" as fast as I can.  I need
to know about branches, how to browse history, merging, conflicts, etc.
It is true, though, that I have a lot of experience doing these things
already by virtue of the fact that I've used VCS's for over a decade and
have been evaluating DVCS's for at least the past 3 years, so I have a
bit of a head start on these things.  To learn about these things,
though, the sheer size of Git's vocabulary is huge compared to other
DVCS's.  That's a *good* thing, but it also makes it a bit harder to
learn it all.  It's just a fact of life.

The first DVCS I learned was monotone.  And I think what helped me the
most in learning it is that it's syntax is very simple (you'd probably
say limited compared to git, but that's neither here nor there, if you
stick to your original list, git is as simple as monotone), it's
repository format, the fact that each developer could keep one
repository and create workspaces off of it was perfect for our
workflows.  What I think really helped with learning monotone is that
they had a bunch of common workflows already documented and we could
simply try them out.  Maybe if Git had a few different workflows
documented that might help.  I know we have a "Git for SVN Users"
workflow, but if you want to move beyond that, it might be good to have
some of the more complex workflows documented.  I think some people have
hinted at that suggestion but that maybe it just hasn't been explicitly
said.

Thanks.
Dscho
--

Cheers,
Craig

On Thu, Jul 17, 2008 at 09:21:58AM -0500, Craig L. Ching wrote:

Maybe if Git had a few different workflows
documented that might help.  I know we have a "Git for SVN Users"
workflow, but if you want to move beyond that, it might be good to have
some of the more complex workflows documented.  I think some people have
hinted at that suggestion but that maybe it just hasn't been explicitly
said.

Yes, very recently, someone on #git asked about existing documented
workflows, and there is very little. It would be interesting project for
someone to build a 'Garden of Git Workflows' (or a Labyrinth) - for each
workflow, detailed self-contained documentation ranging from lone developer
with topic branches over repo.or.cz/github forks workflow, the workflows
of "leaf contributors", lieutenants and main integrators of the mail-oriented
kernel/git workflow, up to the single-central-repository workflows.

There are bits here and there, but the main problem is that they are not
self-contained. It might be nice to have something like a set of military
manuals, appropriate for the roles of the particular developers.

-- 
				Petr "Pasky" Baudis
GNU, n. An animal of South Africa, which in its domesticated state
resembles a horse, a buffalo and a stag. In its wild condition it is
something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce

On Thu, Jul 17, 2008 at 04:51:20PM +0200, Petr Baudis wrote:

On Thu, Jul 17, 2008 at 09:21:58AM -0500, Craig L. Ching wrote:

quoted

Maybe if Git had a few different workflows
documented that might help.  I know we have a "Git for SVN Users"
workflow, but if you want to move beyond that, it might be good to have
some of the more complex workflows documented.  I think some people have
hinted at that suggestion but that maybe it just hasn't been explicitly
said.

Yes, very recently, someone on #git asked about existing documented
workflows, and there is very little. It would be interesting project for
someone to build a 'Garden of Git Workflows' (or a Labyrinth) -

That's been requested for a long time, but nobody's gotten around to it.

It might be nice if it could be made a superset of everyday.txt.

--b.

for each
workflow, detailed self-contained documentation ranging from lone developer
with topic branches over repo.or.cz/github forks workflow, the workflows
of "leaf contributors", lieutenants and main integrators of the mail-oriented
kernel/git workflow, up to the single-central-repository workflows.

There are bits here and there, but the main problem is that they are not
self-contained. It might be nice to have something like a set of military
manuals, appropriate for the roles of the particular developers.

-- 
				Petr "Pasky" Baudis
GNU, n. An animal of South Africa, which in its domesticated state
resembles a horse, a buffalo and a stag. In its wild condition it is
something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html