[darcs-users] Command renamings and hide/show

Marnix Klooster mklooster at baan.nl
Thu May 13 12:02:38 UTC 2004

Hello all,

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
                       recorded' patches
 * invisible unrecorded: changes that have been 'reverted' but could
                         be 'unreverted'.

 * 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
                still recorded.
  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
following renamings:

 * 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:

  inittree         branch
  get              branch

  add              control
  remove           uncontrol

  pull             pull
  push             push
  send             export
  apply            import
  record           record
  rollback         rollback
  unrecord         unrecord
  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 :-)

Marnix Klooster 
mklooster at baan.nl

More information about the darcs-users mailing list