[darcs-users] on the subject of better names...

David Roundy droundy at abridgegame.org
Sun May 9 10:34:20 UTC 2004

On Wed, May 05, 2004 at 07:03:41PM -0700, Adam Megacz wrote:
> David Roundy <droundy at abridgegame.org> writes:
> >> Is there any chance we could merge unrecord and unpull into
> >> deletepatch or destroypatch or something like that?
> >>
> >> My primary gripe is that patches can come from things other than
> >> pulling and recording (rollback is the most confusing example).
> >> There's no "unrollback" command, but since you didn't "pull" or
> >> "record" the rollback patch, people wouldn't think that "unpull" is
> >> the right way to undo a rollback.
> > Well, unpull isn't the right way to undo a rollback, unless you have also
> > performed a revert after the rollback and want to undo both actions, or if
> > you got the rollback via a pull.
> This still has me really, really confused.
> As I understand it, the darcs world consists of:
>   - a pile of patches
>   - a copy of the tree at the time of the last record (_darcs/current)
>   - the working copy

Of these, _darcs/current is redundant with the first.  If it weren't for
the fact that it is so easily corrupted (recently it seems that automake
has taken to inserting new files in _darcs current), the user wouldn't need
to know about it.

This leaves the distinct objects being a pile of patches and a working

> Now, if I understand correctly, 'darcs rollback' adds the inverse
> patch to _darcs/patches and applies it to _darcs/current and the
> working directory as well, right?

No, rollback doesn't affect the working directory.

> > I like the names unrecord and unpull, because they suggest the times when
> > you could use them safely, which means that newbies are hopefully less
> > likely to accidentally shoot themselves in the foot with them.
> Eehhh... I dunno.  If you want to stop people from shooting themselves
> in the foot, a simple "this is irreversible, are you sure?" will work.
> The thing is that with version control, trust is a big issue.  People
> want to know how stuff works before they trust their code to it.  I
> think CVS is popular because it's so simple that everybody understands
> what it's doing when they type a command (with the exception of
> branches, which most people just don't use).

A "this is irreversible" warning only helps if the user understands what
will be irreversibly done.

> I guess it might help people feel more comfortable if (perhaps in
> addition to the existing descriptions) there was a simple model of
> "these are the data structures darcs keeps on the disk" and then
> phrase each command in terms of what it does to those strucures.  Not
> necessarily why it does what it does (which the theory of patches
> explains).

I don't think explaining the data structures kept on the disk is helpful,
but definitely a table explaining which commands affect the working version
and which affect the recorded patches would be helpful.

> >> I guess you could have something like
> >> 
> >>    destroypatch [-k] [-m patchname]
> >> 
> >> where -k would keep the changes in the working copy (like unrecord)
> >> and without -k the working copy would be rolled back as well (unpull).
> > I don't like the idea making unrecord and unpull too similar.  Unrecord is
> > safe, and unrecord is dangerous,

I see I made a typo above.  I meant to say "Unrecord is safe, and unpull is

> I think you mean "rollback is safe".... again, if I understand
> correctly, 'unrecord' destroys the distinction between the last
> recorded patch and whatever changes you've made since then (and hence
> is unsafe), and unpull is even worse as it not only removes the record
> (in _darcs/patches) but the 

I define "safe" in terms of the possibility of losing the user's data.  If
they lose their metadata, they can always rerecord, or group changes
together or whatever.  But if they lose the code that they labored four
days to write, they will not be happy.

Unrecord and rollback can't lose your code.  Unpull can, and revert can.
Of the two dangerous commands, revert is a much better unsafe command than
unpull, since it prompts you for each change you want to revert, giving you
time to notice what exactly is going to be reverted.  In addition, darcs
keeps a copy of the reverted changes, so if you don't do too much in
between, they can be unreverted.

> Not to belabor the point, but perhaps unsafe stuff should have an evil
> word in the name, like "destroy" or "obliterate" or "kill" or perhaps
> even "maim". ;) "Un" doesn't really sound dangerous to me, especially
> in the context of version control.  The "undo" option on the edit menu
> of just about every windows/mac app is "redo-able"...

Right.  The "un" prefix doesn't indicate unsafeness.  Of the "un" commands,
unrecord, unpull and unrevert, only unpull is unsafe.  The "un" part is
intended to indicate which command can be "undone".  Unrecord is the
precise opposite of record.

Unpull is trickier, since it isn't the precise opposite of any command.
But it is perfectly safe to use unpull on a patch that was pulled, so I
prefer that name, which allows people who don't understand the distinction
between unpull and unrecord to easily use the two commands safely and
effectively.  Those who bother to read the manual can then find out that
unpull can also be used to both unrecord a patch and revert its changes
from the working directory.

> > them be a command line flag seems unwise.  At the very minimum, the
> > default would be to unrecord and a flag would be needed to make it an
> > unpull, since at least that way the safe behavior is default.
> Hey now that's a good idea, since unrecord is actually a subset of unpull
> (unpull is effectively unrecord+revert, right?  assuming no unrecorded
> patches in current, of course)
> > But really, I don't think unrecord and unpull should have similar names
> > at all.  Unrecord is a safe tool that you can use regularly without
> > worrying about losing any of your data.
> > Unpull can only be used "safely" on patches that you previously pulled,
> > or on rollback patches that have their corresponding changes reverted.
> Right, but there are a lot of times that I really want to destroy a
> patch.  And it took me a half hour to figure out how -- since I had never
> pulled the patch, I thought "unpull" wouldn't have anything to do with
> it!

What I don't understand is why you didn't just unrecord the patch and then
revert... that is what I would advocate new users (who haven't taken the
half hour to understand unpull) to do.

> > In that respect, revert is already redundant.  But it is usefully
> > redundant.  Adding extra complexity to the revert process seems more
> > likely to cause errors to be made.  There is also the fact that the
> > revert patch can be undone, while unpull can't.
> "revert patch"?  I thought that revert doesn't add anything to
> _darcs/patches.  Am I mistaken?

No, you aren't mistaken.  I meant the revert change.  Revert stores a copy
of what it did to the working directory so you can unrevert it.  I guess if
you have many other changes in the working directory, this could be

> > Of course, undestroypatch functionality
> Er, no...  I was advocating destroyXXXX to be only for irreversible
> operations, so "undestroying" a patch would be impossible (like
> ununpull)...

Since unpull is perfectly safe when used on pulled patches, I'd rather give
it a nice unscary name that reflects that, rather than a scary name.  In my
experience it's very rare that I unpull a patch that wasn't gotten either
by a pull or an apply (and usually it's a pull).
David Roundy

More information about the darcs-users mailing list