Introduction

This manual provides a stable documentation for using darcs. To find more up-to-date and complementary information, please consult the darcs wiki.

Darcs is a revision control system, along the lines of Subversion, Git or Mercurial. That means that it keeps track of various revisions and branches of your project, allows for changes to propagate from one branch to another. Darcs has two particularly distinctive features which differ from other revision control systems:

Every source tree a branch

The primary simplifying notion of darcs is that every copy of your source code is a full repository. This is dramatically different from Subversion, in which the normal usage is for there to be one central repository from which source code will be checked out. This has several advantages, since you can harness the full power of darcs in any scratch copy of your code, without committing your possibly destabilizing changes to a central repository.

Darcs keeps track of changes rather than versions

In the world of darcs, the source tree is not the fundamental object, but rather the patch is the fundamental object. Rather than a patch being defined in terms of the difference between two trees, a tree is defined as the result of applying a given set of patches to an empty tree. Moreover, these patches may be reordered without changing the tree. This makes many operations, like cherry-picking or merging, much more natural.

Features

Record changes locally

In darcs, the equivalent of a svn ``commit'' is called record, because it doesn't put the change into any remote or centralized repository. Changes are always recorded locally, meaning no net access is required in order to work on your project and record changes as you make them.

Interactive records

You can choose to perform an interactive record, in which case darcs will prompt you for each change you have made and ask if you wish to record it. Of course, you can tell darcs to record all the changes in a given file, or to skip all the changes in a given file, or go back to a previous change, or whatever.

Unrecord local changes

As a corollary to the ``local'' nature of the record operation, if a change hasn't yet been published to the world--that is, if the local repository isn't accessible by others--you can safely unrecord a change (even if it wasn't the most recently recorded change) and then re-record it differently, for example if you forgot to add a file, introduced a bug or realized that what you recorded as a single change was really two separate changes.

Interactive everything else

Most darcs commands support an interactive interface. The ``revert'' command, for example, which undoes unrecorded changes has the same interface as record, so you can easily revert just a single change. Pull, push, send and apply all allow you to view and interactively select which changes you wish to pull, push, send or apply.

Test suites

Darcs has support for integrating a test suite with a repository. If you choose to use this, you can define a test command (e.g. ``make check'') and have darcs run that command on a clean copy of the project either prior to recording a change or prior to applying changes--and to reject changes that cause the test to fail.

Any old server

Darcs does not require a specialized server in order to make a repository available for read access. You can use http, ftp, or even just a plain old ssh server to access your darcs repository.

You decide write permissions

Darcs doesn't try to manage write access. That's your business. Supported push methods include direct ssh access (if you're willing to give direct ssh access away), using sudo to allow users who already have shell access to only apply changes to the repository, or verification of gpg-signed changes sent by email against a list of allowed keys. In addition, there is support for submission of patches by email that are not automatically applied, but can easily be applied with a shell escape from a mail reader.

File and directory moves

Renames or moves of files and directories, of course are handled properly, so when you rename a file or move it to a different directory, its history is unbroken, and merges with repositories that don't have the file renamed will work as expected.

Token replace

You can use the ``darcs replace'' command to modify all occurrences of a particular token (defined by a configurable set of characters that are allowed in ``tokens'') in a file. This has the advantage that merges with changes that introduce new copies of the old token will have the effect of changing it to the new token--which comes in handy when changing a variable or function name that is used throughout a project.

Configurable defaults

You can easily configure the default flags passed to any command on either a per-repository or a per-user basis or a combination thereof.