weblog.mattdorn.com

Generously funded by Matt Dorn

Getting started with Darcs

with one comment

The following is a rudimentary set of instructions for setting up, on a Linux server, a Darcs repository which uses the most basic possible method for collaboration, in which a single administrator manually applies patches1 sent him/her via email (automatically, via the darcs send command issued by the contributor).2 Some notes on producing those patches and managing the repository are also included. Further information, including info on how to retract changes, is available in the Darcs manual.

Preparing the central Darcs respository

Upload your public files to where your public repo will be, and then create a repository there, recursively adding the project’s files to it:

cd proj_folder
darcs init
darcs add -r *

Then record a comment for the patch:

darcs record -a

The -a flag will apply all the patches without prompting the user to approve each one. In the case of creating a new project, that means "addfile" patches (which are not really patches in the traditional sense) will be submitted for each file, along with the "hunks" containing the new code represented by the new files.

You can avoid any prompt at all by issuing the command with an extra flag and the patch name:

darcs record -am "Project imported."

The first time you do this, you’ll be prompted to add an email address for the "patch’s author", which in turn will create the _darcs/prefs/author file in your project directory.

Because this will be a basic repository where sent patches will be applied by the administrator, you’ll also want to manually add a file called email to that same directory (_darcs/prefs). That file should contain a single line: the email address of the administrator who will apply the patches. Subsequently issuing of the darcs send command by project contributors will use that email address as the destination for the patch.

You must now make the repository available to remote users. The easiest way to do that is via the Apache Web server. Make a directory in your Apache root called repos and in that directory, and simply symlink to the directory of your Darcs-enabled project. You may have to check to make sure that the appropriate Apache directive allows for following of symlinks. In my case, I also had to make the project directory (and its parent directory, in fact) world-executable.

The main repository is now available for retrieval by collaborators. As the Darcs documentation states, "As long as you’re running a web server and making your repo available to the world, you may as well make it easy for people to see what changes you’ve made." There’s a CGI script that allows users to browse the patch history of your projects. In Ubuntu Linux (Breezy), the darcs-server package handles its installation for you, installing the file /usr/lib/cgi-bin/darcs.cgi. That works out-of-the-box with Ubuntu’s Apache install. If you’ve installed darcs manually, you may have to run make installserver to do the same. Note that you can change the name and location of your repos directory, mentioned above, in /etc/darcs/cgi.conf.

Applying patches

As patches start coming in via email from contributors, you’ll need to apply them to the central repo.

The most direct way to do that would to be to login via a shell to the central repository’s server, and:

cd /path/to/project
darcs apply /path/to/patch

Another possible option is for the project administrator to maintain a local repo in addition to the central repo, apply any patches there (also using darcs apply), and then use his or her shell account to "push" the local repo changes to the central repo server:

darcs push username@website.com:/path/to/repos/proj_name

Contributing to the repo

If you’re a contributor who wants to work with the project for the first time you retrieve it from the Web like so:

darcs get http://www.website.com/repos/proj_name

Now you have a copy of the repo, a fully functional branch.

After working with the project, making changes, etc., you can view the changes you’ve made since your last repo update:

darcs whatsnew

(Add the --summary flag for less verbose output, also add the –look-for-adds flag to see any new files that have been created since your last check-in. You’ll need to add them manually (see below).)

Name your patch and comment on the details of your changes:

darcs record -a

And send them to the central repo (in our case, via email):

darcs send -a

(Note the -a flag in the above two commands, indicating all patches; otherwise you’ll have to approve them one-by-one.)

Note that "darcs send" will fail if you do not have a local mail agent installed. In that case, the best way is simply to output the patch as a file, like so:

darcs send -a --output=/tmp/changes.patch

Note also that if you added any files, you’ll need to explicitly add them to the repo:

darcs add myscript.py

If you want to subsequently pull other contributors’ changes from the repo:

darcs pull http://www.website.com/repos/proj_name

Add the -a flag to avoid being asked to confirm on a per-patch basis.

Tagging versions and getting tagged versions

From the Darcs manual:

While pull and unpull can be used to construct different "versions" in a repository, it is often desirable to name specific configurations of patches so they can be identified and retrieved easily later. This is how darcs implements what is usually known as versions. The command for this is tag, and it records a tag in the current repository.

So, to tag a version 1.0, for example, in the project directory execute:

darcs tag 1.0

And to get the tree for that version later:

darcs get --tag "1.0" http://www.website.com/repos/proj_name
[1]According to Darcs’ "theory of patches," pretty much any change to the tree–including the adding and removing of files–is a "patch."
[2]The Darcs manual describes other methods like the darcs push command, which requires SSH accounts on the server running Darcs for the users collborating on your project, and also includes instructions for an interesting setup involving automatic application of patches arriving via PGP-signed email messages from authorized addresses.

Written by mdorn

April 19th, 2006 at 1:53 pm

Posted in technology

Tagged with , , ,

One Response to 'Getting started with Darcs'

Subscribe to comments with RSS or TrackBack to 'Getting started with Darcs'.

  1. Free darcs repositories for open source projects: patch-tag.com.

    Just upload an ssh key and go.

    Thomas Hartman

    12 May 09 at 3:02 am

Leave a Reply