Working with Darcs

This text assumes that you have already installed darcs and obtained the development version of Carpet, but are possibly too scared or lazy to actually read the darcs manual.


You edit the Carpet source code as usual. At certain times you can say

darcs whatsnew

to find out what you changed. As you have a copy of the Carpet repository stored locally, this will not require an internet connection and will be very fast. One other difference from CVS is that darcs always considers all changes in the repository, and not just changes to a certain file or directory.

If you add or remove files or directories to the repository, say

darcs add FILENAME


darcs remove FILENAME

This does not actually create or delete files; you have to do that yourself. If you move a file or directory, say

darcs mv FROM TO

to tell darcs about that. This does actually perform the move, as indicated by the darcs command mv, which is spelled the same way as the corresponding Unix command.

Recording Changes

If you have implemented a certain feature, corrected a certain error, or fixed a typo, then it is time to record that change as a patch. The command

darcs record

walks you through all your local changes and asks you whether they should be part of the patch. Please put only related changes into a single patch; it is very easy to create multiple patches. Can also be applied to a specific file. To skip the process of verifying each "hunk", use the -a option.

Each patch needs a one-line description. This description should be somewhat descriptive, because other people will decide from this description whether they want this patch or not. "Correct error" will probably not be very helpful, as won't "Use cout instead of printf", because these descriptions do not describe what part of Carpet is actually changed. On the other hand, "Fix typo in comment" is probably good enough. If you feel like it, you can also add a detailed description of the patch. Note that this description should describe the patch, and should not describe how to use a certain feature; this should go into a comment or a README or the documentation.

If you later discover that your patch is incomplete, missing a file, or contains an error, then you can use

darcs amend-record

to correct it. It is often better to correct an erroneous patch than to pile a second patch on top of it. If you think that things are very wrong, then

darcs unrecord

deletes the patch entirely. None of the above commands change your working directory.

Contributing Patches

When you have one or a few patches that you would like to contribute back to the community, then you can use

darcs send

to send these to the Carpet mailing list. The Carpet maintainers can then apply this patch to the Carpet repository, so that the next darcs pull will list this patch for all people. darcs send is the first command described on this page that actually needs network access.

Viewing changes

To view the last n patches applied:

darcs changes --last=n

To see how two patches a and b differ

darcs diff --from-patch=a --to-patch=b

Correcting Errors

Darcs offers a host of commands to undo various actions.

darcs unrecord

was already described above.

darcs unpull

Undoes the effect of pulling a patch from a remote repository. This is useful if you suspect that this patch introduced an error. And

darcs revert

Undoes changes to your working directory that have not yet been recorded. Can also be applied to a specific file.

Further Information

As usual, the authoritative source of information is the darcs manual, which also ships with your darcs installation.

Go back to the Carpet home page.

Valid XHTML 1.0!

Erik Schnetter
Last modified: Wed Jan 24 2007