[darcs-users] new command: darcs put

[Peter Hercek]

Thomas Zander <zander <at> kde.org> writes:
 >
 > On Saturday 19 February 2005 16:11, David Roundy wrote:
 > > To a native english speaker, put is pretty clearly the opposite of get,
 > > but to a non-native speaker, I'm not sure it's obvious, so it could add
 > > some confusion. Having push, pull, get and put might be confusing 
to new
 > > users. On the other hand, pairing them up as in push/pull and put/get
 > > might make things clearer than they currently are.
 > >
 > > But for such a big issue I'd like to see quite a few "yes" votes 
and some
 > > discussion first. Feel free (anyone who cares about this) to start a
 > > fresh thread and/or submit a wishlist bug. If noone cares enough to do
 > > either, I'll assume the status quo must be good enough that it's not
 > > worth the possible confusion of adding a new command.
 >
 > I already mix up revert and rollback quite often, and I feel its 
quite hard
 > to explain what the basic differences are between unrecord and unpull as
 > well. (the --help output could certainly use a hand there..).
 > Thats why I put my vote for 'darcs push --create-target' or similar 
instead
 > of a new top-level command.
 >
 > The reasoning is simple; any piece of software requires some learing 
time
 > and after doing the basic tutorials the user is left to remember the
 > commands based on recognising the choices he has; the output of a simple
 > darcs -h.
 > This means that the recognisability of commands has the direct effect of
 > making the software more usable for all (non-expert) users.
 > Having less choices helps a lot. "get" is a special case since you need
 > that to get started. (we tend to remember the first step a lot better 
then
 > the second).
 >
 > I hope some of my usability experience makes a difference here :)

I'm new to darcs and I'm not native English speaker. Put does not look
confusing to me but anyways...

I do not like -–create-target. What would be created except the remote
repository? --create should be enough :)

This is not only about amount of commands to choose from.
Symmetry helps a lot to remember. Categorizing helps to remember.
Analogies help to remember. One way of doing things and consistency
helps to remember (obviously I'm not a perl guy). Addition of the
option --create instead of the put command is a kind of explicit
categorization.This is better if the interface is not getting too
verbose.

But in this case it breaks symmetry with the get command.

Irregularities are bad for remembering. By adding this as an option,
an irregularity between pull/get and push/--create is created.
Darcs should make interface clean till it is not widely used. So if
the way to go is the explicit categorization it should be followed
in the symmetric case: the option --create should be introduced
for pull and the get command should be dropped. Or leave it as it
is and add the new put command.

In this case I prefer drooping get command and adding -–create to pull.
I think that even the rest of the commands should be categorized in
the help – not by redesign, only by the way they are documented.

Examples of what is bad:
* All the commands are not abbreviated instead of mv. It should be
“move”. The abbreviations should be there, no problem, but in the
help for the move command only. Or maybe after the nonabreviated
form; something like “move, mv Bla, bla, bla...”
* There is amend-record, but on the other side there is setpref.
Should the worlds be divided with hyphen or not? Abbreviation again.
I think amend-record should have been amendrecord. This way it
stays consistent with whatsnew and trackdown.

It should be clearly stated which command works with which data.
An user typically knows what he wants to do. He just needs to
find the right command.
There seem to be 3 data stores in darcs:
* local working copy (whatsnew reports differences in this)
* local repository (patches are stored first in here)
* remote repository (... and then they may be moved around)

The command should be divided based on this in the output of
“darcs –h” too:

Commands which may lead to data loss are marked as unsafe.

Commands for changing and quering working copy:
add Add one or more new files or directories.
remove Remove one or more files or directories.
move Move a file or directory to a different location or name.
replace Replace a token with a new value for that token.
revert Revert to recorded version (safe the first time only).
unrevert Undo the last revert (may fail if any local changes from the 
revert).
whatsnew Display unrecorded changes in the working directory.
Copying data between working copy and local repository:
record Saves working copy changes to repository as a patch.
unrecord Removes a recorded patch (but not the data in working copy).
amendrecord Replaces a recorded patch with a better version.
rollback Applies the inverse patch in repository to the local copy.
resolve Resolve conflicts (records the conflicting patch and the 
resolution).
Setting unversioned (but distributed) properties to local repository:
tag Tag the contents of a repository with a given version name.
setpreference Set the value for a preference (test, predist, ...).
Querying local repository:
diff Create a diff between two versions of the repository.
changes Gives a human-readable list of changes between versions.
annotate Display which patch last modified something, or display patch 
contents
distribution Create a distribution tarball.
trackdown Locate the most recent version lacking an error.
Copying data between repositories:
pull Copies patches from remote to local repository (updates working copy).
unpull Opposite of pull, unsafe if the patch is not in remote repository.
push Copies patches from local to remote repository.
send Send by email a bundle of one or more patches.
apply Apply patches to a repository.
Administration commands (safe):
initialize Initialize a new source tree as a darcs repository.
optimize Optimize your repository.
check Check the repository for consistency.
repair Repair a corrupted repository.


Remarks:

Amendrecord should get a check so that it cannot be used if patch
was already pushed somewhere. If I understand it right it is
super dangerous to do it otherwise.

Amendrecord should not exist; add only –amend option to record and
add the above check (if not there already).

Unpull should check that the patch originated from a remote repository.

Unrecord should check that the patch was not pushed/pulled/send yet.

If the checks are not planed for unpull and unrecord then there
should be only unrecord command with option --revert which
would revert the patch and remove it from local repository.

Get was omitted since it should be pull –-create. Or, alternatively,
we should have both get and put.

It looks like the interface is not complete. How can I return back
a rollback if I had local changes to the file? E.g. I have a files
a.cpp; It is modified. I merge a reverse patch with rollback. Then
I find out that it was not a good idea and I want to merge back the
patch I rolled back. Revert is not good since it would remove my
local changes. Maybe a command "rollforward" is missing. Well
I would prefer to have apply renamed to receive and the apply
would work as rollforward and it would have a switch --back
to work as rollback :)

I guess I just figured out how to remove amendrecord, get and
maybe unpull (depends ont the goal) and increase functionality
and make the interface more orthogonal at the same time
... not bad :-) ... or I just do not understand it :-D

Darcs seems to be a great tool anyways,
Peter.