[darcs-users] Command renamings and hide/show
mklooster at baan.nl
Thu May 13 12:02:38 UTC 2004
Again some ramblings from me. This time on command renamings and
related stuff. This is not a complete story, I just spent an hour or
so thinking about this. Use as you see fit; pick cherries as you
Here is a number of things that would (in my opinion) be very good to
have in darcs, most of them to make it more straightforward for first-
time darcs users.
* Rename 'repository' to 'branch' throughout. This makes the
terminology more consistent with CVS and other systems. Then
explain that a darcs "distributed repository" is simply a collection
of branches that know of each other.
* Make the default to be as verbose as possible, and offer -q /
--quiet (this is the CVS style). This helps beginners.
(Currently it's the other way around.)
* The default should be that no patch is deleted without a warning
and/or special long command line argument. (And the fact the
"unpull" is really destructive and the rest isn't is not really
clear from the name of the command. So renaming is necessary.)
* It should be easy to temporarily get a patch out of the way,
without needing to create a new working directory. So it should
be possible to 'hide' and 'show' patches, modifying the working
directory, but without really modifying the repository. See
* There should be a very simple story based on which all those unpull
/ revert / unrevert / etc. commands can be explained. The rest of
this e-mail contains a very rough outline for such a story, and some
proposed changes based on that.
There are four groups of patches, based on two distinctions:
- visible vs. invisible: is it visible in the working directory?
- recorded vs. unrecorded: is it available for others who read this
This gives four possible combinations:
* visible recorded: everything that is stored in the repository, and
is visible in the working directory.
* visible unrecorded: diff between working directory and the 'visible
* invisible unrecorded: changes that have been 'reverted' but could
* invisible recorded: (currently not in darcs) patches that are in
the repository, but which are 'hidden', so that
they don't show up in the working directory.
I see these linked in the following way:
all visible recorded patches
all visible unrecorded patches (all invisible recorded patches)
all invisible unrecorded patches
Making a patch visible or invisible ('show' or 'hide') moves it up or
down (through commuting) in the tree. (This can of course also draw
with it other dependent patches, which then also are shown or hidden.)
Only visible patches can be recorded, and this moves it up to the
group of 'visible recorded' patches.
Based on the above, I propose the following renamings:
get "branch" or "mkbranch", with explicit option --and-
pull. This indicates that a branch is created. Giving
--and-pull also allows all options of "pull" to be
inittree "branch --root" or "branch --trunk" or just "trunk" or
something like that. I mean, as far as I can see this
is the only place where 'tree' is used, but this is
not in any way related to the way 'branch' is used.
unpull "unrecord --and-delete" or something like that,
protected by a question/permissions/etc. This makes
it clearer that this is a destructive option.
revert "hide --unrecorded", protected by a question
unrevert "show --unrecorded"
The new commands 'hide' and 'show' would be something like this:
hide Changes the working directory, so that the specified
patch(es) are no longer present. The patches are
show Changes the working directory, so that the specified
invisible patches are added to the working directory.
Apart from the above, and a lot less important, I also propose the
* send->export and apply->import: this has more symmetry, and removes
the strange "send --output" combination.
* add->control and remove->uncontrol: this removes any confusion
between "darcs remove" and "rm". (Or perhaps "ignore" instead of
"uncontrol", but that has less symmetry.)
After these renamings we would have the following commands:
unpull unrecord --and-delete
revert hide --unrecorded
unrevert show --unrecorded
I know that this is not simply renaming of commands. At least three
more things need to be done:
- Make sure that patches that have been hidden using "hide --
unrecorded" are treated like any other patch, esp. when adding new
recorded patches using "pull" or "apply".
- Make sure that "show --unrecorded" is guaranteed to work after
"hide --unrecorded". (Right now "unrevert" is only guaranteed if
it is done immediately after "revert".)
- Support 'invisible recorded' patches, which are handled using
"hide" and "show" without the "--unrecorded" flag.
But for darcs 1.0 having only the first two seems to be enough, and
perhaps not too complicated. I don't know.
Enough rambling for now. I'm sure you'll shoot back :-)
mklooster at baan.nl
More information about the darcs-users