caboose

Darcs is, much like Subversion, a source control and management tool. It offers versioning and change tracking, like any SCM. What makes it different from many of its contemporaries is that it is a _distributed_ source control tool. As such, it solves some problems that “centralized” SCMs like Subversion cannot, which can be a big win for developers.

Odds are, as a rails developer you’ve never used Darcs, or other distributed SCMs. So what are they? In Subversion terms, DSCMs allow users to _fork the repository_ and continue work on their own, adding new, independent patches. These changes can actually be _integrated into other forks of the repository_. Each copy of the repository is its own island. This is analogous to a branch in Subversion, but imagine each branch thinks it is actually the main-line of development.

Sound scary? Relax and read on, it’s less scary than you think.

What’s in it for me?

It’s a little hard at first to see what kind of benefit darcs (or any distributed SCM) can bring to your project, so let’s take a moment to see what kind of advantages Darcs brings to the table.

For you as a developer, Darcs is Simple. It is lightweight, requires almost no setup (even less than subversion). It transparently scales from one developer to thousands, so you don’t have to feel hedged by your choice. Darcs makes it very easy to experiment with your code, as well. You can selectively apply and remove patches very easily. It also integrates transparently with PGP/GPG to sign your code distros transparently, and integrates tightly with the concept of unit testing.

For other developers that want to come onto your project, choosing darcs is great. Since every repo is an island, new developers can take the code and work with it as they see fit, selectively sending patches back to you in a variety of ways. They can continue their work even if your servers go down, but still lets them easily sync up with your codebase.

Sounds Good, Where Can I get it?

• Darcs Homepage
• And you probably need the Glasgow Haskell Compiler

Getting Started

After you install the components, you’ll probably want to put some code into a repository. Go to the top level of your repo and type darcs initialize. You’ll notice a new directory called “_darcs” at the top level of your source tree. That’s it. No other steps required, no repos to set up, no .svn directories lurking in each corner.

Probably the first thing you’ll do after that is add your files into your repository. Try darcs add, which works very much like svn add. darcs add -r * from your toplevel will add every file in your repo. Once that’s done, you probably want to commit that as your first change. Here’s the first major difference from subversion. Darcs calls this concept “record”. Darcs’s record command works nearly identically to subversion’s commit feature.

Frequently, you’ll want to check what your current changes are. For this, use darcs whatsnew -s. If you want to look for new files you might want to add, try using darcs whatsnew -s -l, which will show you addables with a lower-case a. If you want to revert your changes back, the conveniently named darcs revert works much like svn revert.

The Weird Part, Moving Code Around

So far, we haven’t done anything that a regular SCM couldn’t do. LEt’s change that. First, darcs record some changes. Then, for fun, let’s go to another directory outside (and not above) our project. Then, type:

darcs get /path/to/your/darcsified/project

This is the equivalent to a svn checkout, but is actually more general even. You’ve basically spun off your own repository, which can now be used. Go inside the project directory, and try changing or adding to the repository. Just:

touch some.new.file
darcs add some.new.file
darcs record -a

Imagine “some.new.file” is a fantastic addition to our new library. Let’s push it back to our main repository:

darcs push

Our change is back in the original repository. No really, that’s it. You have write access, so you can just push it back. This process is how darcs handles what SVN calls branches. You can just spin off a repository, work with it, then pick out the patches you want to send back. It also ensures that other developers don’t have to suffer through a long repository download while you are branching, as in subversion.

What if we want to go the other way? In the the branch repository, we simply say “darcs pull” Darcs will ask us which patches we want to pull (usually you just add an -a flag to the command, it’s seldom that the main repo will contain code you don’t want.)

Didn’t You Say Something About “Distributed”

Yes, as a matter of fact I did. I mentioned that darcs has nearly 0 effort going to a distributed environment. To share darcs over the web, simply make the repository directory available over http. People can use darcs get and darcs pull with a URL argument.

The big difference, of course, is that you can’t write back to an http URL. So what do you do when you’ve come up with a glorious patch you want to share with the maintainer? I introduce, darcs send

darcs send --to=someone@somewhere.com

It sends it via email. Yes, email! This may seem a bit strange, but if you consider it, nearly everyone has an email address, and it’s fairly easy to peruse and filter darcs patches in your inbox. You can preview the patches, and apply them with this gem:

darcs apply patchfile

Oh yes, it’s that easy. Even better, darcs uses unified diffs, so even people who don’t use darcs can easily apply your patches (in fact, many people use darcs even when the project maintainer does not, so that they can easily send patches). You can use GPG to sign (and/or encrypt) the patches.

Going Further

Darcs has a very good manual up on their site. It also has a very complete help feature that works just like subversion’s. Between those two resources, it should be easy to figure out how to make darcs work for you.