The 5-Minute Guide to Contributing With Darcs

Welcome. This will be fast. This guide describes how you can contribute to software projects here using the Darcs version-control system.

Darcs is a distributed VCS, so you do not need to be granted commit access in advance. You can hack, commit, and then send in your patches without permission from anyone.

Step 1: Get Darcs

If you are using Debian, you can simply

apt-get install darcs

. Otherwise, you can download Darcs source or binaries for other Linux, Unix, Windows, and Mac operating systems from the Darcs homepage at http://www.darcs.net/. Instructions will vary depending on your operating system, and are posted on the Darcs site.

Step 2: Tell Darcs who you are

On Unix:

mkdir ~/.darcs
echo "My Name <myemail@example.com>" > ~/.darcs/author

On Windows, this will go under a different location. You can actually omit it and put it in _darcs/prefs/author after you check out the source if you like.

You can even skip this step entirely, but you'll be annoyed because Darcs will ask who you are each time you make a commit if you skip this step.

Step 3: Check Out The Source

You'll run:

darcs get --partial http://darcs.complete.org/projectname
cd projectname

Replace "projectname" with the Darcs name for your project. These names will be given on the project page on this site. One example would be:

darcs get --partial http://darcs.complete.org/offlineimap
cd offlineimap

The [/ Software.Complete.Org project list] and Darcs.Complete.Org project list may be of use to you.

Step 4: Hack

Make your changes. After modifying a file, run:

darcs record -a

You will be asked for a patch name, which is a one-line summary of what you just did. You can, and should, also enter a longer description.

If you add a new file, you'll need to tell Darcs about it before you can use

record

:

darcs add filename

If you rename a file, tell Darcs what you did:

darcs mv oldfilename newfilename

And finally, if you delete a file, Darcs will automatically detect that and send it in as part of the record.

You can leave off the

-a

to record, which will cause Darcs to ask you about each potential change. The

-a

means "all", which tells record to commit all changes you've made.

Step 5: Submit

Once you're done with your feature, submit it to the software manager(s) for consideration. Simply run:

darcs send -a

All version-control history, including your name, commit messages, individual changes, etc. will be e-mailed to the project submission address. Darcs automatically figures out that address from the project repository on complete.org. Darcs also can tell when/if your patches are integrated upstream, and always sends the minimum patch set necessary to bring upstream in sync with your repo.

This, of course, requires a working email setup on your system. You can use

darcs send -o filename

to write a patch bundle to a separate file, which you can then send in manually if email doesn't work for you.

Step 6: Update

If you follow a project for more than a few hours, you'll want to periodically integrate changes from the upstream repository into your local copy.

darcs pull -av

will do this.

Advanced Tips & Tricks

You may also be interested in some of these.

Learning About Commands

darcs --help

will show you a list of commands.

darcs command --help

will show you information about each individual command.

Looking At Changes

You can, of course, use the project timeline here on the website. But for more detailed information, try a command such as:

darcs changes -s | less

You can use

-v

instead of

-s

to see diffs as well.

Your history may not go all the way back to the creation of the project. If you need to do that, check it out again without using

--partial

to

darcs get

. The partial option tells it to download a recent checkpoint, and then play forward only the patches from there. If you leave it off, you will download every single change ever made to the project. This can take quite awhile, consume a lot of disk space, etc. So you should only do that if you really need it -- which will be rarely.

For More Information

Go to the Darcs homepage. There is also a very helpful Wiki and online community on IRC.