Darcs is my favourite version control system because of its simple user interface. I am able to do everything I need with a handful of simple commands. I work with darcs as a single user, without branches, occasionally accepting small external contributions. This guide is designed to provide a sufficient reference for a someone who isn't a computer expert to continue using Darcs after their friendly comp-sci has set up the SSH bits for them (e.g. my wife).
A Darcs repository (or repo) is a set of changes (sometimes referred to as patches). There are three places changes may live:
- Remote Repo, such as on community.haskell.org.
- Local Repo, on your computer. You may have many local repos all using the same remote repo, especially if you use multiple computers.
- Local Changes, modifications you have made to your local repo, by editing files.
The way changes move between locations is described by:
Basic Commands
I use four commands daily, shown in red on the above diagram, which are:
- darcs pull - copy changes from the remote repo to your local repo. Use pull at the beginning of the day, and during the day if you are sharing a remote repo with other people.
- darcs whatsnew - see what local changes you have made. A useful flag is --summary, which lists only the names of files which have changed.
- darcs record - after you have decided to keep your changes, use record to store them in your local repo.
- darcs push --no-set-default ndm@code.haskell.org:/srv/code/hoogle - at the end of the day use push to move your changes to the remote repo. This command is the most tricky to use, you need SSH access to the server and need to use the file path of the repo, not the URL exposed by the website. I recommend writing a .bat file to automate this command, or using the neil push command if appropriate.
In addition to the four commands above, there are two additional basic commands that are used more rarely:
- darcs add filename - tell darcs that you have created a new file that should be kept in the repo. If you forget to add a file, darcs will not store it for you.
- darcs mv oldname newname - rename a file stored in darcs. Use this command instead of directly renaming the file using a file explorer.
Creating Repos
Usually I work with existing repos, but it's useful to know how to create new repos:
- darcs init - create an empty remote repo, with no changes in it. This command is usually run on the server.
- darcs get http://code.haskell.org/hoogle - create a new local repo based on a remote repo.
Advanced Commands
These commands are useful to correct mistakes, but they aren't essential - you can do everything you need without them.
- darcs revert - undo local changes that have not yet been recorded.
- darcs unrecord - undo a previous record command. Do not unrecord if you have pushed the changes, or have done substantial work since the initial record. Instead, manually create a new change undoing the previous record, and record that.
Collaboration Commands
If you are accepting occasional contributions from other people, you will need the following commands:
- darcs send -o filename.patch - make a file containing all the changes in your local repo, but not in the remote repo. This file can be emailed to other people.
- darcs apply filename.patch - apply a set of changes sent to you by email.
Conclusion
Effective use of darcs requires only a few simple commands, with only a few command line switches. This guide includes all the commands I ever use. Darcs rarely surprises me, and I think it is a suitable version control system for people who are familiar with the command line, but aren't computer experts.
