From: Andreas Ericsson <ae@op5.se>
Date: Fri, 18 Jul 2008 08:19:19 GMT
Subject: Re: Considering teaching plumbing to users harmful
Message-ID: <48805207.80504@op5.se>
In-Reply-To: <alpine.DEB.1.00.0807161804400.8950@racer>

Johannes Schindelin wrote:
> Hi,
> 
> there have been a number of occasions where I came across people trying to 
> be helpful and teaching Git newbies a few tricks.
> 
> However, in quite a number of cases, which seem to surge over the last 
> weeks, I see people suggesting the use of rev-parse, ls-tree, rev-list 
> etc.
> 
> Their rationale is invariably "but I found it useful", and they seem to be 
> unable to recognize the puzzlement in the faces of the people they are 
> trying to help.
> 
> Instead they insist that they did nothing wrong.
> 
> I had the pleasure of introducing Git to a few users in the last months 
> and in my opinion, restricting myself to teaching them these commands 
> first helped tremendously:
> 
> - clone, pull, status, add, commit, push, log
> 
> All of these were presented without options, to keep things simple.
> 
> In particular, I refrained from giving them the "-a" option to commit.  
> That seemed to help incredibly with their embracing the index as a natural 
> concept (which it is).
> 
> Often I presented the "pull" and "push" commands _only_ with "origin 
> master" ("origin is where the repository came from, and master is the 
> branch; you will want to use other parameters here after you used Git for 
> a while").
> 
> _After_ they grew comfortable with Git, I taught them a few options here 
> and there, not hiding, but also not promoting the full range of options.
> 
> So the next tricks were
> 
> - log -p, rm, diff, diff --cached, show
> 
> The last one is "show", and with that command, I taught the 
> "<commit>:" and "<commit>:<file>" syntax, too (which some Git old-timers 
> did not know about ;-)
> 

Thanks for the excellent write-up. I wish I'd had this when I did the
introductory courses at my dayjob. With those simple commands, 90%
of the users get access to 90% of the usefulness of git, imo. And,
more importantly, it's enough to get them started right away.


> The pace needed to be adjusted to the users, in my experience, but not the 
> order.
> 
> Now, it makes me really, really sad that Git has a reputation of being 
> complicated, but I regularly hear from _my_ users that they do not 
> understand how that came about.
> 
> Am I the only one who deems teaching plumbing to users ("I like it raw!  
> So I teach it the same way!") harmful?
> 

I wholeheartedly agree. Telling people about "git rev-list" on day one
is probably the single greatest mistake I've ever done wrt git. To the
non-gitizen, it takes some mumbo-jumbo arguments and spits out a long
list of mumbo-jumbo output. Had I started with "git log" instead, it
would have been infinitely easier to explain how each commit has a
totally unique name.

In addition, I'd recommend setting
color.branch=auto
color.diff=auto
color.pager=true
color.status=true
before starting the "course". It makes the learning experience a whole
lot nicer.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231