This chapter will lead you through an example use of darcs, which hopefully will allow you to get started using darcs with your project.
Creating your repository in the first place just involves telling darcs to create the special directory (called _darcs) in your project tree, which will hold the revision information. This is done my simply calling from the root directory of your project:
% cd my_project/ % darcs inittreeThis creates the _darcs directory and populates it with whatever files and directories are needed to describe an empty project. You now need to tell darcs what files and directories in your project should be under revision control. You do this using the command darcs add:
% darcs add *.c Makefile.am configure.inWhen you have added all your files (or at least, think you have), you will want to record your changes. ``Recording'' always includes adding a note as to why the change was made, or what it does. In this case, we'll just note that this is the initial version.
% darcs record --all What is the patch name? Initial revision.Note that since we didn't specify a patch name on the command line we were prompted for one. If the environment variable `EMAIL' isn't set, you will also be prompted for your email address. Each patch that is recorded is given a unique identifier consisting of the patch name, its creator's email address, and the date when it was created.
Now that we have created our repository, make a change to one or more of your files. After making the modification run:
% darcs whatsnewThis should show you the modifications that you just made, in the darcs patch format. If you prefer to see your changes in a different format, read Section 4.4, which describs the whats-new command in detail.
Let's say you have now made a change to your project. The next thing to do is to record a patch. Recording a patch consists of grouping together a set of related changes, and giving them a name. It also tags the patch with the date it was recorded and your email address.
To record a patch simply type:
% darcs recorddarcs will then prompt you with all the changes that you have made that have not yet been recorded, asking you which ones you want to include in the new patch. Finally, darcs will ask you for a name for the patch.
You can now rerun whatsnew, and see that indeed the changes you have recorded are no longer marked as new.
As long as you're running a web browser and making your repo available to
the world, you may as well make it easy for people to see what changes
you've made. You can do this by running make installserver
, which
installs the program darcs_cgi at /usr/lib/cgi-bin/darcs. You
also will need to create a cache directory named
/var/cache/darcs_cgi
, and make sure the owner of that directory is
the same user that your web browser runs as its cgi scripts as. For me,
this is www-data. Now your friends and enemies should be able to easily
browse your repos by pointing their web browsers at http://your.server.org/cgi-bin/darcs. You can read more about this
interface in Chapter 5.
% darcs pull http://your.server.org/repos/yourprojectDarcs will check to see if you have recorded any changes that aren't in my current repository. If so, it'll prompt me for each one, to see which ones I want to add to my repository. Note that you may see a different series of prompts depending your answers, since sometimes one patch depends on another, so if you answer yes to the first one, you won't be prompted for the second if the first depends on it.
Of course, maybe I don't even have a copy of your repository. In that case I'd want to do a
% darcs get --verbose http://your.server.org/repos/yourprojectwhich gets the whole repo.
The darcs patcher (for a few more details see Chapter 6) is a program that allows you to set up a repository to which you can remotely ``push'' patches. Although this isn't necesary to use darcs, it can be useful if you want to give more than one person write access to a repository, or if you do much of your work using a computer on which it is not convenient to run a web server. The patcher receives patches via cryptographically signed email. For each repository you create on a machine a user is created which determines the email address for that repository. Alas, the patcher is considerably harder to set up than darcs itself, which is why this section of the manual is here.
To install the patcher program, you can either install the ``darcs-server'' package (via debian or whatever), or run ``make installserver''. This hopefully will put the programs in the right places.
To use a pushable repository, you also must install the following programs: sudo, gnupg, a mailer configured to receive mail (e.g. exim, sendmail or postfix), and a web server (usually apache). If you want to be able to browse your repository via the web you must also configure your web server to run cgi scripts and make sure the darcs cgi script was properly installed.
To create a repository, as root run the `darcs-createrepo
'. You
will be prompted for the email address of the repository and the location
of an existing copy of the repository. If your desired email is
``myproject@my.url'', this will create a user named ``myproject'' with a
home directory of /var/lib/darcs/repos/myproject
. FIXME: I have no
idea if the darcs-createrepo program will even run on any system other than
debian. Success reports would be appreciated (or of course bug reports if
it fails).
The ``myproject'' user will be configured to run the darcs patcher on any
emails it receives. However, the patcher will bounce any emails which
aren't signed by a key in the
/var/lib/darcs/repos/myproject/allowed_keys
gpg keyring (which is
empty). To give yourself access to this repository you will need to create
a gpg key. If you don't know about public key cryptography, take a look at
the gnupg manual.
You create your gpg key by running (as your normal user):
% gpg --gen-keyYou will be prompted for your name and email address, among other options. To add your public key to the allowed keys keyring. Of course, you can skip this step if you already have a gpg key you wish to use.
You now need to export the public key so we can tell the patcher about it. You can do this will the following comman (again as your normal user):
% gpg --export "email@address" > /tmp/exported_keyAnd now we can add your key to the
allowed_keys
:
(as root)> gpg --keyring /var/lib/darcs/repos/myproject/allowed_keys \ --no-default-keyring --import /tmp/exported_keyYou can repeat this process any number of times to authorize multiple users to push to the repository.
You should now be able to push a patch to the repository by running as your normal user, in a working copy of the repository:
% darcs push --sign http://your.computer/repos/myprojectYou may want to add ``push sign'' to the file
_darcs/prefs/defaults
so that you won't need to type --sign
every time you want to
push...