My Simple Guide to Darcs

I've used a number of revision control systems over the years, but my current favourite is Darcs. It has a fairly simple interface, embodies powerful concepts, and doesn't get in my way (much). Unlike some other systems, it is stable and reliable, and doesn't change how it works every few weeks.

Although you may not be familiar with Darcs, it is very simple to use for the common cases. I've got a quick recipe of how to use darcs to get and work with the branches I provide; if you want more info (especially how to start your own Darcs repositories) I suggest looking at the Darcs Getting Started guide, and also the Darcs reference manual.

The 90 second guide to using Darcs

  1. Get Darcs. Typically, it's as simple as installing one of the pre-built binaries. If you're running Linux and don't see your distribution listed, try the statically-linked binary.
  2. Find the URL of the repository/branch that you want from the project page.
  3. Run darcs get <repository URL> <localdir> to download the repository onto your machine, into the directory <localdir>.
  4. Inspect or edit the source code in <localdir> as you desire.
  5. If you make changes that you want to contribute back, run darcs record. Darcs will ask you some questions to make sure it knows what you want to do (isn't it helpful?), then it will record the patch. (This is analogous to a "commit" in other systems)
  6. To send the patch (or patches!) back to me (for possible inclusion in the main codebase), just run darcs send. That will look for patches that I don't already have, ask you which of those patches you wish to send, then bundle the patches up an e-mail and send them to me.

That's It. Revision control doesn't have to be hard.

Darcs for upstream authors

If you're an upstream wanting to get patches out of my repositories, it's really simple.

  1. Get the repository (as detailed above).
  2. Examine the list of patches in the repository with 'darcs changes'
  3. Run 'darcs diff -u -p <regex>', where <regex> is some sort of regular expression that will match the short description (the first line, next to the '*') of the patch you want.
  4. That will output a unified diff of the changes contained in that patch, ready for application with patch in your own tree.

Of course, if you were running darcs yourself, it would be as simple as darcs pull <repourl>. If you'd like to consider switching to darcs for your project's development, please mail me -- I love helping people reach revision control nirvana.