[darcs-users] should 'changes' be renamed 'log'? (was: Re: SchwernLikesDarcs SchwernHatesDarcs)

Michael G Schwern schwern at pobox.com
Sun Mar 20 20:25:59 UTC 2005

On Sun, Mar 20, 2005 at 12:41:03PM +0100, Thomas Zander wrote:
> On Sunday 20 March 2005 10:45, Michael G Schwern wrote:
> > On Sun, Mar 20, 2005 at 10:13:43AM +0100, Thomas Zander wrote:
> > An alias is not adding a command, its just an additional name for the
> > same command.  You can omit them from the help lists if you like to avoid
> > the extra clutter.
> In your last email you quoted Donald with the "knowledge in the world".  Now 
> you want to walk away from that?

Yes, as a matter of fact.  I pointed out that putting in the command
aliases allows CVS-style users to take advantage of the Knowledge in the 
Head which is faster and more comfortable (as long as its already there).
If a user isn't already comfortable with the CVS command set there's no
advantage for them to learn about it so just don't bring it up.

> > Looking through the list for the command I want, that's only useful if
> > I'm thinking the same way you are.  As mentioned with "change" vs "log"
> > I've been trained to look for "log" from CVS/SVN usage thus it took me a
> > while to notice the "changes" command is what I want.
> The overview of commands needs some love, thats true; also every new tool 
> takes some time to learn.  Fooling our users into believing its a drop in 
> replacement for cvs/svn is certainly going against everything a usability 
> person should be aware about..  Imagine: "The commands are the same, but it 
> does different things!"

There is the opposite extreme.  "It does the same thing, but the commands
are different!"

What I'm discovering so far, for myself, is that for basic operations the 
darcs workflow isn't so different from the CVS/SVN workflow.  You make a
repo.  You add and delete files and directories.  You commit changes.
You diff and annotate.  You look at logs.  You branch by copying (which is
how SVN does it).  These are all operations which are nearly the same as in 
CVS.  The things which are different from CVS, push, pull, send... 
these do have different command names.  And this is good and right.

With any system the faster you can get a user up and usefully working the
more likely it is they'll adopt that system.  darcs can take a leg up in
those crucial first few minutes by using command aliases to let CVS users
feel comfortable with the basic operations which are in common.  I can
teach someone darcs faster than I can teach them Subversion because the
initial setup is so fast and unmagical.  I can use darcs without having
to know about the distributed aspects.  For those crucial first 5 minutes
when the user is being bombarded with new concepts its nice for them to have
something familiar to grab onto.

I don't think anyone's going to be fooled into thinking darcs is a drop
in replacement for CVS, but it doesn't hurt to take advantage of the
similarities where they exist.  You've already got most of it.  add,
remove, mv, diff, annotate which are all similar to CVS.  Two more and
you've got the most important commands covered.

FWIW I haven't read the darcs manual.  I read the "Getting Started" page
on the Wiki and just reference the manual every once in a while.  My existing
knowledge of how version control systems work fills in the rest.

A good example of similarities gone wrong is Ruby to Perl programmers.
Ruby uses $foo and @foo but they mean completely different things than in
Perl.  This leads to confusion for Perl programmers coming to Ruby, reusing 
the same symbol to mean something different in a language which is visually 
similar to Perl.  That is "the commands are the same but they do different 
things".  Aliasing "changes" to "log" doesn't have this problem.  "record" -> 
"commit" might have problems since "recording" a change is different from
sending it back to the master repository and a CVS commit is really both a
record and a send.

Its probably good that "commit" not exist because recording is the point
where the user first encounters the fundamental differences between CVS and 
darcs first appear, where version control becomes distributed.  And that is 
a point where you want them to stop and think.

More information about the darcs-users mailing list