Getting Started with Darcs
Among the plethora of emerging version control systems -- Subversion, Arch, Monotone and so on -- Darcs stands out for its simplicity and thoughtful design.
With darcs you can be productive within minutes; the same cannot be said for Arch or even Subversion. Let's see:
$ mkdir ~/myproject
$ cd ~/myproject
$ darcs init
You now have a Darcs repository! Let's do something with it:
$ touch myfile
$ darcs add -r *
$ darcs record -am "Initial import."
Finished recording patch 'Initial import.'
If that record command is taking too long, then you may prefer this:
$ darcs record --verbose -am "Initial import."
Now your repository contains all your files. Let's look at the changelog:
$ darcs changes
Thu Nov 25 06:26:19 CET 2004 johndoe@example.com
* Initial import.
Note how Darcs generates a GNU-style changelog for you automatically.
Where are the revision numbers, you ask? Well, they don't exist, because they're not needed. Darcs is changeset-oriented, not file-oriented. You can refer to a changeset by name, date, or a special hash identity.
Now, where's the server? You need a server to share your repository, right? Nearly -- every repository is a potential server, as long as it's accessible either through the file system, through SSH/SFTP, HTTP or email. Let's check out a small remote repo to play with:
(NOTE: This repo does not seem to exist - 18th Nov 2007)
$ darcs get http://www.ScannedInAvian.org/repos/wikiwiki
(This URL is not accessible now. -- gphilip)
Copying patch 47 of 47... done!
Applying patches to the "working" directory...
..........................................................................
Finished getting.
We now have a complete copy of a remote repo. Let's make a modification:
$ cd wikiwiki
$ echo 'adding new line to file' >>scribble
$ darcs whatsnew --summary
M ./scribble +1
$ darcs whatsnew
{
hunk ./scribble 2
+adding new line to file
}
This last output, by the way, is Darcs' patch format. A "hunk" is a line-based diff. Other types of changes that may be contained in a changeset include renames, moves and binary changes. (Yes, you can also get a GNU-patch-compatible output similar to "cvs diff", with darcs diff --unified.)
Now let's commit and push the changes back to the remote repository:
$ darcs record -am "Added critical new line." Finished recording patch 'Added critical new line.' $ darcs send -a Creating patch to http://www.ScannedInAvian.org/repos/wikiwiki... Sending by email to wikiwiki@scannedinavian.org Successfully sent patch bundle to wikiwiki@scannedinavian.org.
Some Key Features
Darcs changesets aren't just GNU patches; they have context, which means, for example, that someone can check out a repository, move a file foo.c into the directory bar/ and commit; meanwhile, another person, working on an older copy of the same repository, edits foo.c (which is still in its old location) and commits that. Darcs knows that this edit should apply to foo.c in the new location -- and unlike CVS, you don't need to do anything similar to cvs update if you're committing files that have been changed on the server. In other words, people can freely commit changes, and the only kind of visible "conflict" will occur when you actually edit the exact same line.
Unlike CVS and Subversion, but like Arch and Monotone, Darcs is a distributed version control system. Repositories are islands which are constantly out of sync with each other, and Darcs' patch commutation system takes care of integrating the changes that flow between them.
This system has several extremely useful effects:
Offline mode. You can commit changes even if you're on the road with no access to the server. That's because your own working directory is a repository in its own right. When you get home, you do a "darcs push" to commit to the public server.
Easy branching. Every repository is a branch. Working on implementing some feature but need to fix a bug? You don't want to check in your work in progress just to check in a bugfix, so you branch off the trunk and work on the fix.
Linus mode. I want to add a feature or bugfix to an open-source project. I make a local Darcs copy, apply my changes, then send my changes by email ("darcs send"). The project's maintainer(s) can decide whether to accept or reject the changes. This way, you don't necessarily need to screw around with commit privileges. This is how Darcs itself is maintained, by the way. This is also similar to the way Linux is/was maintained, except the process is implemented in software.
Parallel development. Let's say I follow the development of this open-source project, and I have some "controversial" patches that aren't accepted by the official maintainers. No problem -- I make my changes, release my own distribution. It's a fork, of sorts, but it's still connected to the mainline. Whenever the official project makes changes, I do a "darcs pull" to get them, and resolve any conflicts. This way, my fork is kept up to date with the main project's repository.
Easy local revision control. CVS/RCS is popular for versioning home directories, /etc, etc. With Darcs you get the simplicity of RCS with the power of, well, Darcs. Maintaining the same config on a myriad of PCs becomes easier, not least because Darcs supports pushing of changes; I can make changes and push them to all my servers with a single command. (But see the questions about permissions in the Frequently Asked Questions)
Cherry-picking. If you've ever worked on a team, you will know that somebody often has a change you want, but which can't be committed to the trunk yet. With Darcs you can grab just the one change by pulling it into your repository.
Related Pages
A brief introduction to Darcs, from Carpetcode.org
Another short how-to from zwiki.org
Understanding Darcs - the wikibook