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 by simply calling from the root directory of your project:
$ cd my_project/ $ darcs initializeThis 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.acWhen 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.
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
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.
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 .
cd
into their repository,
and there type:
$ darcs pull http://your.server.org/repos/yourprojectDarcs 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 http://your.server.org/repos/yourprojectwhich 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
.
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.
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.
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 droundy@abridgegame.org --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