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
from within the OpenEngine directory.
More information on Darcs can be found in the Quick Start below or at darcs.net
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.
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.
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
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 http://repository.com/repository/path
sends the changes to some other repository if possible.
You can communicate with repositories over ssh. Just use
darcs pull/push username@host:/absolute/path/to/repository
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!)