Darcs is the version control system we have chosen for our project. First  get Darcs for your favorite platform. You may find a more efficient way of obtaining darcs by reading one of our build guides for you particular platform.

After installing Darcs you can grab our source with:

darcs get http://www.daimi.au.dk/~cgd/openengine openengine

From then on you may update the source by running

darcs pull

from within the OpenEngine directory.

More information on Darcs can be found in the Quick Start below or at  darcs.net

Quick start

To get started using darcs you may read the quick start below or you can read the very nice  wiki book about darcs.

Darcs is a very cool reversion control system. It is decentralized/distributed meaning that there is no need for a central repository. Every copy is a repository in its own right.

This is very handy when working off line or if you do not have a server some where to host a central repository. But it also eases the way in which others can branch the code and work on it in other directions.

Ok, nuff said. Here are the basics you need to start off.

Common problems

Not all is perfect so you must take care of the following:

Never push conflicts!

This will trigger an outstanding bug in darcs called the  exponential merge problem and it is not nice!

Check out the  Conflicts FAQ for a detailed description on conflict handling.

Do not change line endings.

Darcs does not try to be smart about line endings. If you change the line ending of a line you have changed the line. Therefor if you change the line endings of the entire file you potentially conflict with the entire file and there is a very good chance that you will encounter the dreaded  exponential merge problem.

It does not matter what line ending you use and you may use different line endings in different files. Just don't change the ending once you have recorded it in darcs. Some editors want to save a file with a certain line ending. If your editor does this find a new editor. All decent editors will allow you to automatically use the line ending already in use in the current file.

Help

Entering darcs without options or darcs help will give you a list of all the options it has.

Getting the source

The first time you wish to obtain a copy of a repository you run

darcs get http://repository.com/repository/path  local-name

Updating your copy

To update your copy from a given repository you type

darcs pull http://repository.com/repository/path

or

darcs pull

if you wish to update from the same repository as you ran update/commit/checkout on the last time.

(You will most likely only need to run it without a repository path, but most modern shells - bash, zsh - will allow you to tab-complete)

Committing your changes

To commit changes you need to perform a few things.

First you may use darcs add path/to/new/file to add files that are not already in the repository.

Then run darcs record this will interactively prompt you on each hunk of code that has changed. Pressing y confirms that the hunk should go into the patch and n tells it that the hunk should not be included. (? for help)

This gives you the possibility of only recording some of the changes you have made to a file, while other undone (or unwanted changes) can be left out of this patch.

You can always run darcs record again to record the remaining hunks under a different patch name.

After you have recorded the changes you have made you can commit them to some other repository. This is called pushing.

darcs push

or

darcs push http://repository.com/repository/path

sends the changes to some other repository if possible.

SSH

You can communicate with repositories over ssh. Just use

darcs pull/push username@host:/absolute/path/to/repository

or

darcs pull/push username@host:path/from/home/to/repository

If you would like to get rid of the password prompts you can use a ssh key with ssh agent. ~/.ssh/authorized_keys gives you the possibility to add others keys as valid login keys (use with great care!)