next up previous contents
Next: Configuring darcs Up: Darcs User Manual Previous: Introduction   Contents


Getting started

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

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 by simply calling from the root directory of your project:

$ cd my_project/
$ darcs initialize
This 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
When 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, the date when it was created, and a random hash.

Making changes

Now that we have created our repository, make a change to one or more of your files. After making the modification run:

$ darcs whatsnew
This 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 [*], which describes the whatsnew 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 record
darcs 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.

Making your repository visible to others

How do you let the world know about these wonderful changes? Obviously, they must be able to see your repository. Currently the easiest way to do this is is to look for hosting services for darcs repositories.

You can also self-host your repositories by using any web server. The recommended way to do this (using apache in a UNIX environment) is to create a directory called /var/www/repos, and then put a symlink to your repository there:

$ cd /var/www/repos
$ ln -s /home/username/myproject .

Getting changes made to another repository

Ok, so your repository is browsable using any web browser... so what? How does one get your changes into their repository, where they can do some good? It couldn't be easier. One just cd into their repository, and there type:
$ darcs pull
Darcs will check to see if you have recorded any changes that aren't in their current repository. If so, it'll prompt them for each one, to see which ones one want to add to their repository. Note that you may see a different series of prompts depending on 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 people don't even have a copy of your repository. In that case they'd want to do a

$ darcs get
which gets the whole repository.

Get, pull and push also work over ssh. Ssh-paths are of the same form accepted by scp, namely [username@]host:/path/to/repository.

Moving patches from one repository to another

Darcs is flexible as to how you move patches from one repository to another. This section will introduce all the ways you can get patches from one place to another, starting with the simplest and moving to the most complicated.


If you use ssh, you can use the push method to transfer changes. Push can also be used when the target repository is local, in which case ssh isn't needed.

Note that you can use push to administer a multiple-user repository. You just need to create a user for the repository (or repositories), and give everyone with write access ssh access, perhaps using .ssh/authorized_keys. Then they run

$ darcs push repouser@repo.server:repo/directory

If you like this idea about creating a repository user to own a repository which is writable by a number of users, you have one other option.

Push --apply-as can run on either a local repository or one accessed with ssh, but uses sudo to run a darcs apply command (having created a patch bundle as in send) as another user. You can add the following line in your sudoers file to allow the users to apply their patches to a centralized repository:

ALL   ALL = (repo-user) NOPASSWD: /usr/bin/darcs apply --all --repodir /repo/path*
This method is ideal for a centralized repository when all the users have accounts on the same computer, if you don't want your users to be able to run arbitrary commands as repo-user.

All pulls

This method involves making each repository readable (by http, ftp, nfs-mounted disk, or a public web hosting), and you run darcs pull in the repository you want to move the patch to. This is nice, as it doesn't require you to give write access to anyone else, and is reasonably simple.

Send and apply manually

Sometimes the push method is impossible because the owner of the main repository does not want or cannot create a user to write into it, and you cannot use the all-pull method because you cannot set up a web server on your machine, perhaps because it's behind a firewall or perhaps for security reasons, or because it is often turned off. In this case you can use darcs send from that computer to generate a patch bundle for the remote repository. You can either let darcs email the patch for you, or save it as a file and transfer it by hand. Then in the destination repository the owner of that repository runs darcs apply to apply the patches contained in the bundle. This is also quite a simple method since, like the all-pull method, it doesn't require that you give anyone write access to your repository. But it's less convenient, since the owner of the remote repository has to keep track of the patch bundle (in the email, or whatever).

To use the send and apply method with email, the best is probably to create a _darcs/prefs/email file in the target repository containing the email address of the maintainer. This way anyone who sends to this repository will automatically send the patch bundle to that email address.

If you receive many patches by email, you probably will benefit by running darcs apply directly from your mail program. You can place in your .muttrc the following:

auto_view text/x-patch text/x-darcs-patch
macro pager A "<pipe-entry>darcs apply --verbose --mark-conflicts \
        --reply --repodir ~/darcs"
which will allow you to view a sent patch, and then apply the patch directly from mutt, sending a confirmation email to the person who sent you the patch. The autoview line relies on on the following lines, or something like them, being present in one's .mailcap:
text/x-patch;                           cat; copiousoutput
text/x-darcs-patch;                     cat; copiousoutput

next up previous contents
Next: Configuring darcs Up: Darcs User Manual Previous: Introduction   Contents
Daniil 2014-02-06