1 Source code management with darcs: a first look {anchor:Source code management with darcs: a first look} I have been managing the [LectroTest] project with the {link:monotone|http://www.venge.net/monotone/} revision control system. For the last few months, monotone has been undergoing some growing pains that have made it less stable than I would like for everyday use. Thus I thought that I would give [darcs] a try. I have been following the progress of darcs since it was first announced on the Haskell-Cafe mailing list on 9 April 2003. Darcs is written in [Haskell], one of my favorite programming languages, and that was my initial draw. Still, until yesterday I had never used it for any of my projects because I felt it was immature and needed some more real-world testing before I committed work to it. In the last three months, Darcs has gained mainstream attention (triggered by a {link:favorable write-up in Linux Weekly News|http://lwn.net/Articles/110516/}) and a growing user base. Under the gaze of these new eyeballs, darcs has matured much. I thought it was time for another look. Darcs has a small, easy-to-understand command set and yet offers "modern" source-code management features such as distributed development (via HTTP, ssh, and email), change sets, and cherry picking. Want to start an experimental branch of your project? Just check out another copy and use it for the branch. Each working copy is a complete, independent repo. Want to publish a project repository to the world? Just copy it to a public web server. Want to start working on someone else's project? A single "darcs get http:\/\/other.project.com/project" gives you a complete, stand-alone copy. Your own personal branch. Start hacking. To try darcs on something I was familiar with, I decided manage my [LectroTest] development with it. The first thing I did was change to the LT working directory and use "darcs init" to create a darcs repository there. {code:none} \[tom@bifur Flippi]$ __cd ~/work/research/perl/qc/ __~~# LT root dir~~ \[tom@bifur qc]$ __darcs init__ \[tom@bifur qc]$ __l__ blib/ mt.db _build/ mtdb.dump Build\* perl-Test-LectroTest-0.2007-1.src.rpm Build.PL pod2htmd.tmp Build.PL~ pod2htmi.tmp buildrpm\* posts/ buildrpm~ prop2.pl Changes prop2.pl~ Changes~ README checkpods\* t/ checkpods~ Test-LectroTest-0.2001.tar.gz ctime.pl Test-LectroTest-0.2002.tar.gz ctime.pl~ Test-LectroTest-0.2003.tar.gz CVS/ Test-LectroTest-0.2004.tar _darcs/ Test-LectroTest-0.2004.tar.gz Example1.pl~ Test-LectroTest-0.2005.tar.gz lib/ Test-LectroTest-0.2006.tar.gz Makefile.PL Test-LectroTest-0.2007.tar.gz MANIFEST Test-LectroTest-0.2008.tar.gz MANIFEST~ Test-LectroTest-0.2009.tar.gz MANIFEST.bak Test-LectroTest-0.201.tar.gz MANIFEST.SKIP tex/ MANIFEST.SKIP~ THANKS META.yml THANKS~ monotone.db TODO monotone.db.bak TODO~ monotone.db.pre-changesets toms-notes.txt monotone.db-pre-sql3 toms-notes.txt~ MT/ {code} You can see that there is a lot of accumulated cruft in my working directory, including CVS, monotone, and now darcs revision-control artifacts. To prevent Perl's Module::Build from thinking the ~~_darcs~~ directory is meaningful, I added it to the manifest-skip file. {code:none} \[tom@bifur qc]$ __echo '\\\b_darcs\\\b' >> MANIFEST.SKIP__ {code} Next I added my LectroTest sources, docs, and related files to the darcs repo. {code:none} \[tom@bifur qc]$ __darcs add Build.PL buildrpm Changes__ \\\ __checkpods MANIFEST MANIFEST.SKIP tex THANKS TODO__ \\\ __toms-notes.txt tex/Makefile tex/titlepage.ltx__ {code} The "darcs whatsnew" command asks darcs to tell me what is changed in the working directory with respect to the repository state. {code:none} \[tom@bifur qc]$ __darcs whatsnew -s__ A ./Build.PL A ./Changes A ./MANIFEST A ./MANIFEST.SKIP A ./THANKS A ./TODO A ./buildrpm A ./checkpods A ./tex/ A ./tex/Makefile A ./tex/titlepage.ltx A ./toms-notes.txt {code} The files that I added are new because I had not yet recorded them to the repository. Before I did that, I added the remaining LT assets. {code:none} \[tom@bifur qc]$ __darcs add t __~~# add the tests dir~~ \[tom@bifur qc]$ __darcs add t/\*.t__ \[tom@bifur qc]$ __darcs add lib__ \[tom@bifur qc]$ __cd lib__ \[tom@bifur lib]$ __l__ Test/ \[tom@bifur lib]$ __darcs add Test__ \[tom@bifur lib]$ __cd Test__ \[tom@bifur Test]$ __l__ LectroTest/ LectroTest.pm~ LectroTest::Tutorial.pod~ LectroTest.pm LectroTest.pm.bak \[tom@bifur Test]$ __darcs add LectroTest LectroTest.pm__ \[tom@bifur Test]$ __cd LectroTest__ \[tom@bifur LectroTest]$ __l__ Compat.pm Generator.pm~ Simple.pm~ Tutorial.pod Compat.pm~ Generator.pm.bak Test.pm~ Tutorial.pod~ Compat.pm.bak Property.pm TestRunner.pm Tutorial.pod.bak CVS/ Property.pm~ TestRunner.pm~ Generator.pm Property.pm.bak TestRunner.pm.bak \[tom@bifur LectroTest]$ __darcs add \*.pm \*.pod__ {code} At this point, it looked like I had all of the files under darcs's watchful eye. {code:none} \[tom@bifur LectroTest]$ __darcs w -s __~~# abbreviated: w -> whatsnew~~ A ./Build.PL A ./Changes A ./MANIFEST A ./MANIFEST.SKIP A ./THANKS A ./TODO A ./buildrpm A ./checkpods A ./lib/ A ./lib/Test/ A ./lib/Test/LectroTest/ A ./lib/Test/LectroTest.pm A ./lib/Test/LectroTest/Compat.pm A ./lib/Test/LectroTest/Generator.pm A ./lib/Test/LectroTest/Property.pm A ./lib/Test/LectroTest/TestRunner.pm A ./lib/Test/LectroTest/Tutorial.pod A ./t/ A ./t/001.t A ./t/002.t A ./t/003.t A ./t/004.t A ./t/005.t A ./t/compat.t A ./tex/ A ./tex/Makefile A ./tex/titlepage.ltx A ./toms-notes.txt \[tom@bifur LectroTest]$ __cd ../../.. __~~# back up to project home~~ {code} That looked right. It was time to record my changes. This was straightforward. {code:none} \[tom@bifur qc]$ __darcs record --all __~~# record all changes~~ Darcs needs to know what name (conventionally an email address) to use as the patch author, e.g. 'Fred Bloggs <fred@bloggs.invalid>'. If you provide one now it will be stored in the file '_darcs/prefs/author' and used as a default in the future. To change your preferred author address, simply delete or edit this file. What is your email address? __Tom Moertel <tom@moertel.com>__ What is the patch name? __Initial checkin of sources__ Do you want to add a long comment? \[yn] __n__ Finished recording patch 'Initial checkin of sources' {code} Now what did darcs think has changed? {code:none} \[tom@bifur qc]$ __darcs w -s__ No changes! {code} Excellent. One cool feature of darcs is that every working directory is also a complete, independent repository. To make a branch, then, is as simple as checking out a new repository. Of course, because there is no central repository in the darcs model, "checking out" is a concept that does not really apply. Rather, what I must do is set up a new repository and then "push" my existing repository's patches to it. I can push in many ways, including via ssh to a remotely hosted repository, but here I will just set up a new repo in /tmp and push to it on the local filesystem. {code:none} \[tom@bifur qc]$ __mkdir /tmp/lt && pushd /tmp/lt__ /tmp/lt ~/work/research/perl/qc \[tom@bifur lt]$ __darcs init __~~# set up new repo at /tmp/lt~~ \[tom@bifur lt]$ __popd__ ~/work/research/perl/qc \[tom@bifur qc]$ __darcs push /tmp/lt __~~# push to repo at /tmp/lt~~ Sat Feb 12 01:26:15 EST 2005 Tom Moertel <tom@moertel.com> \* Initial checkin of sources Shall I push this patch? (1/1) \[ynWvxqadjk], or ? for help: __y__ Finished applying... {code} Now, I can begin working on my new branch in the /tmp/lt working directory. {code:none} \[tom@bifur qc]$ __cd /tmp/lt__ \[tom@bifur lt]$ __l__ Build.PL Changes _darcs/ MANIFEST posts/ tex/ TODO buildrpm checkpods lib/ MANIFEST.SKIP t/ THANKS toms-notes.txt \[tom@bifur lt]$ __emacs lib/Test/LectroTest.pm __~~# fix typo~~ \[tom@bifur lt]$ __darcs record__ hunk ./lib/Test/LectroTest.pm 38 \-of your software. LectroTest then checks your software see whether \+of your software. LectroTest then checks your software to see whether Shall I record this patch? (1/1) \[ynWsfqadjk], or ? for help: __y__ What is the patch name? __Fixed stupid typo in intro text of T::LectroTest.pm__ Do you want to add a long comment? \[yn] __n__ Finished recording patch 'Fixed stupid typo in intro text of T::LectroTest.pm' {code} Now my branch repository contains two patches: {code:none} \[tom@bifur lt]$ __darcs changes__ Sat Feb 12 13:20:07 EST 2005 Tom Moertel <tom@moertel.com> \* Fixed stupid typo in intro text of T::LectroTest.pm Sat Feb 12 01:26:15 EST 2005 Tom Moertel <tom@moertel.com> \* Initial checkin of sources {code} Because the typo that I fixed is not unique to my new branch, I ought to make sure that the original branch gets the fix, too. To do so, I just push it: {code:none} \[tom@bifur lt]$ __darcs push ~/work/research/perl/qc__ Pushing to /home/thor/work/research/perl/qc... Sat Feb 12 13:20:07 EST 2005 Tom Moertel <tom@moertel.com> * Fixed stupid typo in intro text of T::LectroTest.pm Shall I push this patch? (1/1) [ynWvxqadjk], or ? for help: __y__ Finished applying... {code} And now my patch has been pushed back up to the mainstream branch! ~~This~~ is an attractive development model. So far, I like darcs. Its source code–management model is simple and powerful. Its command set is small enough to actually grok. Using darcs has me wondering why other SCM systems have made the problem seem so complicated. My life is complicated enough as it is. I think I just switched to darcs. 2005-02-12 17:55:39.075 2005-02-12 17:55:39.075