<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Darcs $darcs_version$</title>
<meta name="author" content="David Roundy" />
<meta name="copyright" content="© 2002, 2003 David Roundy" />
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="header">
###Title###
<hr class="header"/>
</div>
<div class="document" id="darcs-darcs-version">
<h1 class="title">Darcs $darcs_version$</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Roundy</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>© 2002, 2003 David Roundy</td></tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">This program is free software; you can redistribute it and/or modify
it under the terms of the <a class="reference external" href="http://www.gnu.org/licenses/gpl2.html">GNU General Public License</a> as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.</p>
<p>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.</p>
<p class="last">You should have received a copy of the GNU General Public License
along with this program; see the file COPYING. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.</p>
</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents-at-a-glance">
<p class="topic-title first">Contents at a Glance</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id20">Introduction</a></li>
<li><a class="reference internal" href="#building-darcs" id="id21">Building darcs</a></li>
<li><a class="reference internal" href="#getting-started" id="id22">Getting started</a></li>
<li><a class="reference internal" href="#configuring-darcs" id="id23">Configuring darcs</a></li>
<li><a class="reference internal" href="#best-practices" id="id24">Best practices</a></li>
<li><a class="reference internal" href="#repository-formats" id="id25">Repository formats</a></li>
<li><a class="reference internal" href="#darcs-commands" id="id26">Darcs commands</a></li>
</ul>
</div>
<!-- Comment: the following declarations are for rst2pdf. -->
<div class="contents topic" id="detailed-table-of-contents">
<p class="topic-title first">Detailed Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id27">Introduction</a><ul>
<li><a class="reference internal" href="#features" id="id28">Features</a></li>
<li><a class="reference internal" href="#switching-from-cvs" id="id29">Switching from CVS</a></li>
<li><a class="reference internal" href="#switching-from-arch" id="id30">Switching from arch</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-darcs" id="id31">Building darcs</a><ul>
<li><a class="reference internal" href="#prerequisites" id="id32">Prerequisites</a></li>
<li><a class="reference internal" href="#building-on-mac-os-x" id="id33">Building on Mac OS X</a></li>
<li><a class="reference internal" href="#building-on-microsoft-windows" id="id34">Building on Microsoft Windows</a></li>
<li><a class="reference internal" href="#building-from-tarball" id="id35">Building from tarball</a></li>
<li><a class="reference internal" href="#building-darcs-from-the-repository" id="id36">Building darcs from the repository</a></li>
<li><a class="reference internal" href="#submitting-patches-to-darcs" id="id37">Submitting patches to darcs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#getting-started" id="id38">Getting started</a><ul>
<li><a class="reference internal" href="#creating-your-repository" id="id39">Creating your repository</a></li>
<li><a class="reference internal" href="#making-changes" id="id40">Making changes</a></li>
<li><a class="reference internal" href="#making-your-repository-visible-to-others" id="id41">Making your repository visible to others</a></li>
<li><a class="reference internal" href="#getting-changes-made-to-another-repository" id="id42">Getting changes made to another repository</a></li>
<li><a class="reference internal" href="#moving-patches-from-one-repository-to-another" id="id43">Moving patches from one repository to another</a></li>
<li><a class="reference internal" href="#reducing-disk-space-usage" id="id44">Reducing disk space usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-darcs" id="id45">Configuring darcs</a><ul>
<li><a class="reference internal" href="#environment-variables" id="id46">Environment variables</a></li>
<li><a class="reference internal" href="#general-purpose-variables" id="id47">General-purpose variables</a></li>
<li><a class="reference internal" href="#remote-repositories" id="id48">Remote repositories</a></li>
<li><a class="reference internal" href="#highlighted-output" id="id49">Highlighted output</a></li>
<li><a class="reference internal" href="#character-escaping-and-non-ascii-character-encodings" id="id50">Character escaping and non-ASCII character encodings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#best-practices" id="id51">Best practices</a><ul>
<li><a class="reference internal" href="#id4" id="id52">Introduction</a></li>
<li><a class="reference internal" href="#creating-patches" id="id53">Creating patches</a></li>
<li><a class="reference internal" href="#using-patches-still-basics" id="id54">Using patches % still basics</a></li>
<li><a class="reference internal" href="#enable-a-global-cache" id="id55">Enable a Global Cache</a></li>
<li><a class="reference internal" href="#distributed-development-with-one-primary-developer" id="id56">Distributed development with one primary developer</a></li>
<li><a class="reference internal" href="#development-by-a-small-group-of-developers-in-one-office" id="id57">Development by a small group of developers in one office</a></li>
<li><a class="reference internal" href="#personal-development" id="id58">Personal development</a></li>
</ul>
</li>
<li><a class="reference internal" href="#repository-formats" id="id59">Repository formats</a><ul>
<li><a class="reference internal" href="#id19" id="id60">Introduction</a></li>
<li><a class="reference internal" href="#darcs-1-format" id="id61">Darcs 1 format</a></li>
<li><a class="reference internal" href="#hashed-format" id="id62">Hashed format</a></li>
<li><a class="reference internal" href="#darcs-2-format" id="id63">Darcs 2 format</a></li>
</ul>
</li>
<li><a class="reference internal" href="#darcs-commands" id="id64">Darcs commands</a><ul>
<li><a class="reference internal" href="#options-apart-from-darcs-commands" id="id65">Options apart from darcs commands</a></li>
<li><a class="reference internal" href="#getting-help" id="id66">Getting help</a></li>
<li><a class="reference internal" href="#creating-repositories" id="id67">Creating repositories</a></li>
<li><a class="reference internal" href="#modifying-the-contents-of-a-repository" id="id68">Modifying the contents of a repository</a></li>
<li><a class="reference internal" href="#working-with-changes" id="id69">Working with changes</a></li>
<li><a class="reference internal" href="#seeing-what-you-ve-done" id="id70">Seeing what you've done</a></li>
<li><a class="reference internal" href="#more-advanced-commands" id="id71">More advanced commands</a></li>
<li><a class="reference internal" href="#undoing-redoing-and-running-in-circles" id="id72">Undoing, redoing and running in circles</a></li>
<li><a class="reference internal" href="#advanced-examination-of-the-repository" id="id73">Advanced examination of the repository</a></li>
<li><a class="reference internal" href="#rarely-needed-and-obscure-commands" id="id74">Rarely needed and obscure commands</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id27">Introduction</a></h1>
<p>Darcs is a revision control system, along the lines of CVS or arch. 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
is intended to be an "advanced" revision control system. Darcs has two
particularly distinctive features which differ from other revision control
systems: 1) each copy of the source is a fully functional branch, and 2)
underlying darcs is a consistent and powerful theory of patches.</p>
<dl class="docutils">
<dt>Every source tree a branch</dt>
<dd>The primary simplifying notion of darcs is that <em>every</em> copy of your
source code is a full repository. This is dramatically different from CVS,
in which the normal usage is for there to be one central repository from
which source code will be checked out. It is closer to the notion of arch,
since the "normal" use of arch is for each developer to create his own
repository. However, darcs makes it even easier, since simply checking out
the code is all it takes to create a new repository. 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.</dd>
<dt>Theory of patches</dt>
<dd>The development of a simplified theory of patches is what originally
motivated me to create darcs. This patch formalism means that darcs patches
have a set of properties, which make possible manipulations that couldn't be
done in other revision control systems. First, every patch is invertible.
Secondly, sequential patches (i.e. patches that are created in sequence, one
after the other) can be reordered, although this reordering can fail, which
means the second patch is dependent on the first. Thirdly, patches which are
in parallel (i.e. both patches were created by modifying identical trees)
can be merged, and the result of a set of merges is independent of the order
in which the merges are performed. This last property is critical to darcs'
philosophy, as it means that a particular version of a source tree is fully
defined by the list of patches that are in it, i.e. there is no issue
regarding the order in which merges are performed. For a more thorough
discussion of darcs' theory of patches, see Appendix <a href="#id75"><span class="problematic" id="id76">Patch_</span></a>.</dd>
<dt>A simple advanced tool</dt>
<dd>Besides being "advanced" as discussed above, darcs is actually also quite
simple. Versioning tools can be seen as three layers. At the foundation is
the ability to manipulate changes. On top of that must be placed some kind
of database system to keep track of the changes. Finally, at the very top is
some sort of distribution system for getting changes from one place to
another.</dd>
</dl>
<p>Really, only the first of these three layers is of particular interest to
me, so the other two are done as simply as possible. At the database
layer, darcs just has an ordered list of patches along with the patches
themselves, each stored as an individual file. Darcs' distribution system
is strongly inspired by that of arch. Like arch, darcs uses a dumb server,
typically apache or just a local or network file system when pulling
patches. darcs has built-in support for using <tt class="docutils literal"><span class="pre">ssh</span></tt> to write to a remote file
system. A darcs executable is called on the remote system to apply the patches.
Arbitrary other transport protocols are supported, through an environment
variable describing a command that will run darcs on the remote system.
See the documentation for DARCS_APPLY_FOO in Chapter <a class="reference internal" href="#configuring-darcs">Configuring Darcs</a>
for details.</p>
<p>The recommended method is to send patches through gpg-signed email
messages, which has the advantage of being mostly asynchronous.</p>
<dl class="docutils">
<dt>Keeping track of changes rather than versions</dt>
<dd>In the last paragraph, I explained revision control systems in terms of
three layers. One can also look at them as having two distinct uses. One
is to provide a history of previous versions. The other is to keep track
of changes that are made to the repository, and to allow these changes to
be merged and moved from one repository to another. These two uses are
distinct, and almost orthogonal, in the sense that a tool can support one
of the two uses optimally while providing no support for the other. Darcs
is not intended to maintain a history of versions, although it is possible
to kludge together such a revision history, either by making each new patch
depend on all previous patches, or by tagging regularly. In a sense, this
is what the tag feature is for, but the intention is that tagging will be
used only to mark particularly notable versions (e.g. released versions, or
perhaps versions that pass a time consuming test suite).</dd>
</dl>
<p>Other revision control systems are centered upon the job of keeping track
of a history of versions, with the ability to merge changes being added as
it was seen that this would be desirable. But the fundamental object
remained the versions themselves.</p>
<p>In such a system, a patch (I am using patch here to mean an encapsulated
set of changes) is uniquely determined by two trees. Merging changes that
are in two trees consists of finding a common parent tree, computing the
diffs of each tree with their parent, and then cleverly combining those two
diffs and applying the combined diff to the parent tree, possibly at some
point in the process allowing human intervention, to allow for fixing up
problems in the merge such as conflicts.</p>
<p>In the world of darcs, the source tree is <em>not</em> 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 (unless there are dependencies
between the patches involved) without changing the tree. As a result,
there is no need to find a common parent when performing a merge. Or, if
you like, their common parent is defined by the set of common patches, and
may not correspond to any version in the version history.</p>
<p>One useful consequence of darcs' patch-oriented philosophy is that since a
patch need not be uniquely defined by a pair of trees (old and new), we can
have several ways of representing the same change, which differ only in how
they commute and what the result of merging them is. Of course, creating
such a patch will require some sort of user input. This is a Good Thing,
since the user <em>creating</em> the patch should be the one forced to think
about what he really wants to change, rather than the users merging the
patch. An example of this is the token replace patch (See
Section <a href="#id77"><span class="problematic" id="id78">token_replace_</span></a>). This feature makes it possible to create a
patch, for example, which changes every instance of the variable
"stupidly_named_var" to "better_var_name", while leaving
"other_stupidly_named_var" untouched. When this patch is merged with
any other patch involving the "stupidly_named_var", that instance will
also be modified to "better_var_name". This is in contrast to a more
conventional merging method which would not only fail to change new
instances of the variable, but would also involve conflicts when merging
with any patch that modifies lines containing the variable. By more using
additional information about the programmer's intent, darcs is thus able to
make the process of changing a variable name the trivial task that it
really is, which is really just a trivial search and replace, modulo
tokenizing the code appropriately.</p>
<p>The patch formalism discussed in Appendix <a href="#id79"><span class="problematic" id="id80">Patch_</span></a> is what makes darcs'
approach possible. In order for a tree to consist of a set of patches,
there must be a deterministic merge of any set of patches, regardless of the
order in which they must be merged. This requires that one be able to
reorder patches. While I don't know that the patches are required to be
invertible as well, my implementation certainly requires invertibility. In
particular, invertibility is required to make use of
Theorem <a href="#id81"><span class="problematic" id="id82">merge_thm_</span></a>, which is used extensively in the manipulation of
merges.</p>
<div class="section" id="features">
<h2><a class="toc-backref" href="#id28">Features</a></h2>
<dl class="docutils">
<dt>Record changes locally</dt>
<dd>In darcs, the equivalent of a cvs "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. Moreover, this
means that there is no need for a separate "disconnected operation" mode.</dd>
<dt>Interactive records</dt>
<dd>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. There is also an experimental graphical interface, which
allows you to view and choose changes even more easily, and in whichever
order you like.</dd>
<dt>Unrecord local changes</dt>
<dd>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.</dd>
<dt>Interactive everything else</dt>
<dd>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.</dd>
<dt>Test suites</dt>
<dd>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.</dd>
<dt>Any old server</dt>
<dd>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.</dd>
<dt>You decide write permissions</dt>
<dd>Darcs doesn't try to manage write access. That's your business. Supported
push methods include direct ssh access (if you're willing to <em>give</em>
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 good 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 (this is how I deal with contributions to darcs).</dd>
<dt>Symmetric repositories</dt>
<dd>Every darcs repository is created equal (well, with the exception of a
"partial" repository, which doesn't contain a full history...), and every
working directory has an associated repository. As a result, there is a
symmetry between "uploading" and "downloading" changes—you can use
the same commands (push or pull) for either purpose.</dd>
<dt>CGI script</dt>
<dd>Darcs has a CGI script that allows browsing of the repositories.</dd>
<dt>Portable</dt>
<dd>Darcs runs on UNIX (or UNIX-like) systems (which includes Mac OS X) as well
as on Microsoft Windows.</dd>
<dt>File and directory moves</dt>
<dd>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.</dd>
<dt>Token replace</dt>
<dd>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.</dd>
<dt>Configurable defaults</dt>
<dd>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.</dd>
</dl>
</div>
<div class="section" id="switching-from-cvs">
<h2><a class="toc-backref" href="#id29">Switching from CVS</a></h2>
<p>Darcs is refreshingly different from CVS.</p>
<p>CVS keeps version controlled data in a central repository, and
requires that users check out a working directory whenever they wish
to access the version-controlled sources. In order to modify the
central repository, a user needs to have write access to the central
repository; if he doesn't, CVS merely becomes a tool to get the latest
sources.</p>
<p>In darcs there is no distinction between working directories and
repositories. In order to work on a project, a user makes a local
copy of the repository he wants to work in; he may then harness the
full power of version control locally. In order to distribute his
changes, a user who has write access can <em>push</em> them to the
remote repository; one who doesn't can simply send them by e-mail in a
format that makes them easy to apply on the remote system.</p>
<dl class="docutils">
<dt>Darcs commands for CVS users</dt>
<dd><p class="first">Because of the different models used by cvs and darcs, it is
difficult to provide a complete equivalence between cvs and darcs.
A rough correspondence for the everyday commands follows:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">CVS</th>
<th class="head">Darcs</th>
<th class="head">Remarks</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>cvs checkout</td>
<td>darcs get</td>
<td> </td>
</tr>
<tr><td>cvs update</td>
<td>darcs pull</td>
<td> </td>
</tr>
<tr><td>cvs -n update</td>
<td>darcs pull --dry-run</td>
<td>summarize remote
changes</td>
</tr>
<tr><td>cvs -n update</td>
<td>darcs whatsnew
--summary</td>
<td>summarize local
changes</td>
</tr>
<tr><td>cvs -n update | grep
'?'</td>
<td>darcs whatsnew -ls |
grep ^a</td>
<td>list potential files
to add</td>
</tr>
<tr><td>rm foo.txt; cvs
update foo.txt</td>
<td>darcs revert foo.txt</td>
<td>revert to foo.txt
from repo</td>
</tr>
<tr><td>cvs diff</td>
<td>darcs whatsnew</td>
<td>if checking local
changes</td>
</tr>
<tr><td>cvs diff</td>
<td>darcs diff</td>
<td>if checking recorded
changes</td>
</tr>
<tr><td>cvs commit</td>
<td>darcs record</td>
<td>if committing
locally</td>
</tr>
<tr><td>cvs commit</td>
<td>darcs tag</td>
<td>if marking a version
for later use</td>
</tr>
<tr><td>cvs commit</td>
<td>darcs push or darcs
send</td>
<td>if committing
remotely</td>
</tr>
<tr><td>cvs diff | mail</td>
<td>darcs send</td>
<td> </td>
</tr>
<tr><td>cvs add</td>
<td>darcs add</td>
<td> </td>
</tr>
<tr><td>cvs tag -b</td>
<td>darcs get</td>
<td> </td>
</tr>
<tr><td>cvs tag</td>
<td>darcs tag</td>
<td> </td>
</tr>
</tbody>
</table>
</dd>
<dt>Migrating CVS repositories to darcs</dt>
<dd>Tools and instructions for migrating CVS repositories to darcs are provided
on the darcs community website:
<a class="reference external" href="http://darcs.net/DarcsWiki/ConvertingFromCvs">http://darcs.net/DarcsWiki/ConvertingFromCvs</a></dd>
</dl>
</div>
<div class="section" id="switching-from-arch">
<h2><a class="toc-backref" href="#id30">Switching from arch</a></h2>
<p>Although arch, like darcs, is a distributed system, and the two systems
have many similarities (both require no special server, for example), their
essential organization is very different.</p>
<p>Like CVS, arch keeps data in two types of data structures:
repositories (called "archives") and working directories. In order
to modify a repository, one must first check out a corresponding
working directory. This requires that users remember a number of
different ways of pushing data around --- <tt class="docutils literal"><span class="pre">tla</span></tt> <tt class="docutils literal"><span class="pre">get</span></tt>,
<tt class="docutils literal"><span class="pre">update</span></tt>, <tt class="docutils literal"><span class="pre">commit</span></tt>, <tt class="docutils literal"><span class="pre">archive-mirror</span></tt> and so on.</p>
<p>In darcs, on the other hand, there is no distinction between working
directories and repositories, and just checking out your sources
creates a local copy of a repository. This allows you to harness the
full power of version control in any scratch copy of your sources, and
also means that there are just two ways to push data around:
<tt class="docutils literal"><span class="pre">darcs</span></tt> <tt class="docutils literal"><span class="pre">record</span></tt>, which stores edits into your local
repository, and <tt class="docutils literal"><span class="pre">pull</span></tt>, which moves data between repositories.
(<tt class="docutils literal"><span class="pre">darcs</span></tt> <tt class="docutils literal"><span class="pre">push</span></tt> is merely the opposite of <tt class="docutils literal"><span class="pre">pull</span></tt>;
<tt class="docutils literal"><span class="pre">send</span></tt> and <tt class="docutils literal"><span class="pre">apply</span></tt> are just the two halves of <tt class="docutils literal"><span class="pre">push</span></tt>).</p>
<dl class="docutils">
<dt>Darcs commands for arch users</dt>
<dd><p class="first">Because of the different models used by arch and darcs, it is
difficult to provide a complete equivalence between arch and darcs.
A rough correspondence for the everyday commands follows:</p>
<table border="1" class="last docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Arch</th>
<th class="head">Darcs</th>
<th class="head">Remarks</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>tla init-tree</td>
<td>darcs initialize</td>
<td> </td>
</tr>
<tr><td>tla get</td>
<td>darcs get</td>
<td> </td>
</tr>
<tr><td>tla update</td>
<td>darcs pull</td>
<td> </td>
</tr>
<tr><td>tla file-diffs f |
patch -R</td>
<td>darcs revert</td>
<td> </td>
</tr>
<tr><td>tla changes -diffs</td>
<td>darcs whatsnew</td>
<td> </td>
</tr>
<tr><td>tla logs</td>
<td>darcs changes</td>
<td> </td>
</tr>
<tr><td>tla file-diffs</td>
<td>darcs diff -u</td>
<td> </td>
</tr>
<tr><td>tla add</td>
<td>darcs add</td>
<td> </td>
</tr>
<tr><td>tla mv</td>
<td>darcs mv</td>
<td>not tla move</td>
</tr>
<tr><td>tla commit</td>
<td>darcs record</td>
<td>if committing
locally</td>
</tr>
<tr><td>tla commit</td>
<td>darcs tag</td>
<td>if marking a version
for later use</td>
</tr>
<tr><td>tla commit</td>
<td>darcs push or darcs
send</td>
<td>if committing
remotely</td>
</tr>
<tr><td>tla archive-mirror</td>
<td>darcs pull or darcs
push</td>
<td> </td>
</tr>
<tr><td>tla tag</td>
<td>darcs get</td>
<td>if creating a branch</td>
</tr>
<tr><td>tla tag</td>
<td>darcs tag</td>
<td>if creating a tag</td>
</tr>
</tbody>
</table>
</dd>
<dt>Migrating arch repositories to darcs</dt>
<dd>Tools and instructions for migrating arch repositories to darcs are provided
on the darcs community website:
<a class="reference external" href="http://darcs.net/DarcsWiki/ConvertingFromArch">http://darcs.net/DarcsWiki/ConvertingFromArch</a></dd>
</dl>
</div>
</div>
<div class="section" id="building-darcs">
<h1><a class="toc-backref" href="#id31">Building darcs</a></h1>
<p>This chapter should walk you through the steps necessary to build darcs for
yourself. There are in general two ways to build darcs. One is for
building released versions from tarballs, and the other is to build the
latest and greatest darcs, from the darcs repo itself.</p>
<p>Please let me know if you have any problems building darcs, or don't have
problems described in this chapter and think there's something obsolete
here, so I can keep this page up-to-date.</p>
<div class="section" id="prerequisites">
<h2><a class="toc-backref" href="#id32">Prerequisites</a></h2>
<p>To build darcs you will need to have <tt class="docutils literal"><span class="pre">ghc</span></tt>, the Glorious Glasgow
Haskell Compiler. You should have at the very minimum version 6.4.</p>
<p>It is a good idea (but not required) to have software installed that provide darcs
network access. The <tt class="docutils literal"><span class="pre">libwww-dev</span></tt>, <tt class="docutils literal"><span class="pre">libwww-ssl-dev</span></tt> or <tt class="docutils literal"><span class="pre">libcurl</span></tt> packages
newer than than 7.18.0 are recommended because they provide pipelining support speed
up HTTP access. They have to be explicitly chosen with <tt class="docutils literal"><span class="pre">--with-libwww</span></tt> or
<tt class="docutils literal"><span class="pre">--with-curl-pipelining</span></tt>. Otherwise, darcs will automatically look for one of
libcurl, <tt class="docutils literal"><span class="pre">curl</span></tt> or <tt class="docutils literal"><span class="pre">wget</span></tt>. You also might want to have scp
available if you want to grab your repos over ssh...</p>
<p>To use the <tt class="docutils literal"><span class="pre">diff</span></tt> command of darcs, a <tt class="docutils literal"><span class="pre">diff</span></tt> program supporting
options <tt class="docutils literal"><span class="pre">-r</span></tt> (recursive diff) and <tt class="docutils literal"><span class="pre">-N</span></tt> (show new files as
differences against an empty file) is required. The <tt class="docutils literal"><span class="pre">configure</span></tt>
script will look for <tt class="docutils literal"><span class="pre">gdiff</span></tt>, <tt class="docutils literal"><span class="pre">gnudiff</span></tt> and <tt class="docutils literal"><span class="pre">diff</span></tt> in this
order. You can force the use of another program by setting the <tt class="docutils literal"><span class="pre">DIFF</span></tt>
environment variable before running <tt class="docutils literal"><span class="pre">configure</span></tt>.</p>
<p>To rebuild the documentation (which should not be necessary since it is
included in html form with the tarballs), you will need to have latex
installed, as well as latex2html if you want to build it in html form.</p>
</div>
<div class="section" id="building-on-mac-os-x">
<h2><a class="toc-backref" href="#id33">Building on Mac OS X</a></h2>
<p>To build on Mac OS X, you will need the Apple Developer Tools and the ghc
6.4 package installed.</p>
</div>
<div class="section" id="building-on-microsoft-windows">
<h2><a class="toc-backref" href="#id34">Building on Microsoft Windows</a></h2>
<p>To build on Microsoft Windows, you will need:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.mingw.org/">MinGW</a> which provides the GCC toolchain for win32.</li>
<li><a class="reference external" href="http://www.mingw.org/msys.shtml">MSYS</a> which provides a unix build environment for win32. Be sure to download the separate
msysDTK, autoconf and automake.</li>
<li><a class="reference external" href="http://www.gzip.org/zlib/">zlib</a> 1.2.1 or higher library and headers.</li>
<li><a class="reference external" href="http://curl.haxx.se/">curl</a> 7.12.2 or higher library
and headers.</li>
<li>If building with an SSL enabled curl you will need the OpenSSL
libraries, unofficial builds are available at
<a class="reference external" href="http://www.slproweb.com/products/Win32OpenSSL.html">http://www.slproweb.com/products/Win32OpenSSL.html</a>.</li>
</ul>
<p>Copy the zlib and curl libraries and headers to both GHC and MinGW. GHC
stores C headers in <tt class="docutils literal"><span class="pre"><ghc-dir>/gcc-lib/include</span></tt> and libraries in
<tt class="docutils literal"><span class="pre"><ghc-dir>/gcc-lib</span></tt>. MinGW stores headers in
<tt class="docutils literal"><span class="pre"><mingw-dir>/include</span></tt> and libraries in <tt class="docutils literal"><span class="pre"><mingw-dir>/lib</span></tt>.</p>
<p>Set PATH to include the <tt class="docutils literal"><span class="pre"><msys-dir>/bin</span></tt>, <tt class="docutils literal"><span class="pre"><mingw-dir>/bin</span></tt>,
<tt class="docutils literal"><span class="pre"><curl-dir></span></tt>, and a directory containing a pre-built darcs.exe if you
want the build's patch context stored for <tt class="docutils literal"><span class="pre">`darcs</span> <span class="pre">--exact-version</span></tt>'.</p>
<pre class="literal-block">
C:\darcs> cd <darcs-source-dir>
C:\darcs> sh
$ export GHC=/c/<ghc-dir>/bin/ghc.exe
$ autoconf
$ ./configure --target=mingw
$ make
</pre>
</div>
<div class="section" id="building-from-tarball">
<h2><a class="toc-backref" href="#id35">Building from tarball</a></h2>
<p>If you get darcs from a tarball, the procedure (after unpacking the tarball
itself) is as follows:</p>
<pre class="literal-block">
% ./configure
% make
# Optional, but recommended
% make test
% make install
</pre>
<p>There are options to configure that you may want to check out with</p>
<pre class="literal-block">
% ./configure --help
</pre>
<p>If your header files are installed in a non-standard location, you may need
to define the <tt class="docutils literal"><span class="pre">CFLAGS</span></tt> and <tt class="docutils literal"><span class="pre">CPPFLAGS</span></tt> environment variables to
include the path to the headers. e.g. on NetBSD, you may need to run</p>
<pre class="literal-block">
% CFLAGS=-I/usr/pkg/include CPPFLAGS=-I/usr/pkg/include ./configure
</pre>
</div>
<div class="section" id="building-darcs-from-the-repository">
<h2><a class="toc-backref" href="#id36">Building darcs from the repository</a></h2>
<p>To build the latest darcs from its repository, you will first need a
working copy of Darcs 2. You can get darcs using:</p>
<pre class="literal-block">
% darcs get -v http://darcs.net/
</pre>
<p>and once you have the darcs repository you can bring it up to date with a</p>
<pre class="literal-block">
% darcs pull
</pre>
<p>The repository doesn't hold automatically generated files, which include
the configure script and the HTML documentation, so you need to run
<tt class="docutils literal"><span class="pre">autoconf</span></tt> first.</p>
<p>You'll need <tt class="docutils literal"><span class="pre">autoconf</span></tt> 2.50 or higher. Some systems have more than one
version of <tt class="docutils literal"><span class="pre">autoconf</span></tt> installed. For example, <tt class="docutils literal"><span class="pre">autoconf</span></tt> may point to
version 2.13, while <tt class="docutils literal"><span class="pre">autoconf259</span></tt> runs version 2.59.</p>
<p>Also note that <tt class="docutils literal"><span class="pre">make</span></tt> is really "GNU make". On some systems, such as
the BSDs, you may need to type <tt class="docutils literal"><span class="pre">gmake</span></tt> instead of make for this to work.</p>
<p>If you want to create readable documentation you'll need to have latex installed.</p>
<pre class="literal-block">
% autoconf
% ./configure
% make
% make install
</pre>
<p>If you want to tweak the configure options, you'll need to run {tt
./configure} yourself after the make, and then run make again.</p>
</div>
<div class="section" id="submitting-patches-to-darcs">
<h2><a class="toc-backref" href="#id37">Submitting patches to darcs</a></h2>
<p>I know, this doesn't really belong in this chapter, but if you're using the
repository version of darcs it's really easy to submit patches to me using
darcs. In fact, even if you don't know any Haskell, you could submit fixes
or additions to this document (by editing <tt class="docutils literal"><span class="pre">building_darcs.tex</span></tt>) based
on your experience building darcs...</p>
<p>To do so, just record your changes (which you made in the darcs repository)</p>
<pre class="literal-block">
% darcs record --no-test
</pre>
<p>making sure to give the patch a nice descriptive name. The
<tt class="docutils literal"><span class="pre">--no-test</span></tt> options keeps darcs from trying to run the unit tests,
which can be rather time-consuming. Then you can send the patch to the
darcs-devel mailing list by email by</p>
<pre class="literal-block">
% darcs send
</pre>
<p>If you are using darcs 2.0.0 or earlier, please use</p>
<pre class="literal-block">
% darcs send -u
</pre>
<p>instead.
The darcs repository stores the email address to which patches should be
sent by default. The email address you see is actually my own, but when
darcs notices that you haven't signed the patch with my GPG key, it will
forward the message to darcs-devel.</p>
</div>
</div>
<div class="section" id="getting-started">
<h1><a class="toc-backref" href="#id38">Getting started</a></h1>
<p>This chapter will lead you through an example use of darcs, which hopefully
will allow you to get started using darcs with your project.</p>
<div class="section" id="creating-your-repository">
<h2><a class="toc-backref" href="#id39">Creating your repository</a></h2>
<p>Creating your repository in the first place just involves telling darcs to
create the special directory (called <tt class="docutils literal"><span class="pre">_darcs</span></tt>) in your project tree,
which will hold the revision information. This is done by simply calling
from the root directory of your project:</p>
<pre class="literal-block">
% cd my_project/
% darcs initialize
</pre>
<p>This creates the <tt class="docutils literal"><span class="pre">_darcs</span></tt> 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 <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">add</span></tt>: <a class="footnote-reference" href="#id3" id="id2">[1]</a></p>
<pre class="literal-block">
% darcs add *.c Makefile.am configure.ac
</pre>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Note that darcs does not do wildcard expansion, instead relying
on the command shell. The Windows port of darcs has a limited form of
expansion provided by the C runtime:</td></tr>
</tbody>
</table>
<p>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.</p>
<pre class="literal-block">
% darcs record --all
What is the patch name? Initial revision.
</pre>
<p>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.</p>
</div>
<div class="section" id="making-changes">
<h2><a class="toc-backref" href="#id40">Making changes</a></h2>
<p>Now that we have created our repository, make a change to one or more of
your files. After making the modification run:</p>
<pre class="literal-block">
% darcs whatsnew
</pre>
<p>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 <a href="#id83"><span class="problematic" id="id84">whatsnew_</span></a>, which describes the whatsnew command in
detail.</p>
<p>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.</p>
<p>To record a patch simply type:</p>
<pre class="literal-block">
% darcs record
</pre>
<p>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.</p>
<p>You can now rerun whatsnew, and see that indeed the changes you have
recorded are no longer marked as new.</p>
</div>
<div class="section" id="making-your-repository-visible-to-others">
<h2><a class="toc-backref" href="#id41">Making your repository visible to others</a></h2>
<p>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 typically by http using any web server. The recommended way to do
this (using apache in a UNIX environment) is to create a directory called
<tt class="docutils literal"><span class="pre">/var/www/repos</span></tt>, and then put a symlink to your repository there:</p>
<pre class="literal-block">
% cd /var/www/repos
% ln -s /home/username/myproject .
</pre>
<p>As long as you're running a web server and making your repository 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 <tt class="docutils literal"><span class="pre">make</span> <span class="pre">installserver</span></tt>, which
installs the program <tt class="docutils literal"><span class="pre">darcs_cgi</span></tt> at <tt class="docutils literal"><span class="pre">/usr/lib/cgi-bin/darcs</span></tt>. You
also will need to create a cache directory named
<tt class="docutils literal"><span class="pre">/var/cache/darcs_cgi</span></tt>, and make sure the owner of that directory is
the same user that your web server runs its cgi scripts as. For me,
this is www-data. Now your friends and enemies should be able to easily
browse your repositories by pointing their web browsers at
<tt class="docutils literal"><span class="pre">http://your.server.org/cgi-bin/darcs</span></tt>.</p>
</div>
<div class="section" id="getting-changes-made-to-another-repository">
<h2><a class="toc-backref" href="#id42">Getting changes made to another repository</a></h2>
<p>Ok, so I can now browse your repository using my web browser... so
what? How do I get your changes into <em>my</em> repository, where they can
do some good? It couldn't be easier. I just <tt class="docutils literal"><span class="pre">cd</span></tt> into my repository,
and there type:</p>
<pre class="literal-block">
% darcs pull http://your.server.org/repos/yourproject
</pre>
<p>Darcs 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 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.</p>
<p>Of course, maybe I don't even have a copy of your repository. In that case
I'd want to do a</p>
<pre class="literal-block">
% darcs get http://your.server.org/repos/yourproject
</pre>
<p>which gets the whole repository.</p>
<p>I could instead create an empty repository and fetch all of your patches
with pull. Get is just a more efficient way to clone a whole repository.</p>
<p>Get, pull and push also work over ssh. Ssh-paths are of the same form
accepted by scp, namely <tt class="docutils literal"><span class="pre">[username@]host:/path/to/repository</span></tt>.</p>
</div>
<div class="section" id="moving-patches-from-one-repository-to-another">
<h2><a class="toc-backref" href="#id43">Moving patches from one repository to another</a></h2>
<p>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.</p>
<div class="section" id="all-pulls">
<h3>All pulls</h3>
<p>The simplest method is the "all-pull" method. This involves making each
repository readable (by http, ftp, nfs-mounted disk, whatever), and you
run <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">pull</span></tt> 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.</p>
</div>
<div class="section" id="send-and-apply-manually">
<h3>Send and apply manually</h3>
<p>Sometimes you have a machine on which it is not convenient to set up a web
server, 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
<tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">send</span></tt>
from that computer to generate a patch bundle destined for another
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 you
(or the owner of that repository) run <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">apply</span></tt> 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 you have to keep track of the
patch bundle (in the email, or whatever).</p>
<p>If you use the send and apply method with email, you'll probably want to
create a <tt class="docutils literal"><span class="pre">_darcs/prefs/email</span></tt> file containing your email address.
This way anyone who sends to your repository will automatically send the
patch bundle to your email address.</p>
<p>If you receive many patches by email, you probably will benefit by running
darcs apply directly from your mail program. I have in my <tt class="docutils literal"><span class="pre">.muttrc</span></tt>
the following:</p>
<pre class="literal-block">
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"
</pre>
<p>which allows me to view a sent patch, and then apply the patch directly from <tt class="docutils literal"><span class="pre">mutt</span></tt>, sending a
confirmation email to the person who sent me the patch. The autoview line relies on on the following
lines, or something like them, being present in one's <tt class="docutils literal"><span class="pre">.mailcap</span></tt>:</p>
<pre class="literal-block">
text/x-patch; cat; copiousoutput
text/x-darcs-patch; cat; copiousoutput
</pre>
</div>
<div class="section" id="push">
<h3>Push</h3>
<p>If you use ssh (and preferably also ssh-agent, so you won't have to keep
retyping your password), you can use the push method to transfer changes
(using the scp protocol for communication). This method is again not very
complicated, since you presumably already have the ssh permissions set up.
Push can also be used when the target repository is local, in which case
ssh isn't needed. On the other hand, in this situation you could as easily
run a pull, so there isn't much benefit.</p>
<p>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
<tt class="docutils literal"><span class="pre">.ssh/authorized_keys</span></tt>. Then they run</p>
<pre class="literal-block">
% darcs push repouser@repo.server:repo/directory
</pre>
</div>
<div class="section" id="push-apply-as">
<h3>Push ---apply-as</h3>
<p>Now we get more subtle. If you like the idea in the previous paragraph
about creating a repository user to own a repository which is writable by
a number of users, you have one other option.</p>
<p>Push <tt class="docutils literal"><span class="pre">--apply-as</span></tt> can run on either a local repository or one accessed
with ssh, but uses <tt class="docutils literal"><span class="pre">sudo</span></tt> 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 <tt class="docutils literal"><span class="pre">sudoers</span></tt> file to allow the users to apply their patches to a
centralized repository:</p>
<pre class="literal-block">
ALL ALL = (repo-user) NOPASSWD: /usr/bin/darcs apply --all --repodir /repo/path*
</pre>
<p>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.</p>
</div>
<div class="section" id="sending-signed-patches-by-email">
<h3>Sending signed patches by email</h3>
<p>Most of the previous methods are a bit clumsy if you don't want to give
each person with write access to a repository an account on your server. Darcs
send can be configured to send a cryptographically signed patch by email.
You can then set up your mail system to have darcs verify that patches were
signed by an authorized user and apply them when a patch is received by
email. The results of the apply can be returned to the user by email.
Unsigned patches (or patches signed by unauthorized users) will be
forwarded to the repository owner (or whoever you configure them to be
forwarded to...).</p>
<p>This method is especially nice when combined with the <tt class="docutils literal"><span class="pre">--test</span></tt> option
of darcs apply, since it allows you to run the test suite (assuming you
have one) and reject patches that fail—and it's all done on the server,
so you can happily go on working on your development machine without
slowdown while the server runs the tests.</p>
<p>Setting up darcs to run automatically in response to email is by far the
most complicated way to get patches from one repository to another... so it'll
take a few sections to explain how to go about it.</p>
<dl class="docutils">
<dt>Security considerations</dt>
<dd><p class="first">When you set up darcs to run apply on signed patches, you should assume
that a user with write access can write to any file or directory that is
writable by the user under which the apply process runs. Unless you
specify the <tt class="docutils literal"><span class="pre">--no-test</span></tt> flag to darcs apply (and this is <em>not</em>
the default), you are also allowing anyone with write access to that
repository to run arbitrary code on your machine (since they can run a test
suite—which they can modify however they like). This is quite a
potential security hole.</p>
<p class="last">For these reasons, if you don't implicitly trust your users, it is
recommended that you create a user for each repository to limit the damage
an attacker can do with access to your repository. When considering who to
trust, keep in mind that a security breach on any developer's machine could
give an attacker access to their private key and passphrase, and thus to
your repository.</p>
</dd>
<dt>Installing necessary programs</dt>
<dd>You also must install the following programs: 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 on the web you
must also configure your web server to run cgi scripts and make sure the
darcs cgi script was properly installed (by either a darcs-server package,
or "make install-server").</dd>
<dt>Granting access to a repository</dt>
<dd><p class="first">You create your gpg key by running (as your normal user):</p>
<pre class="literal-block">
% gpg --gen-key
</pre>
<p>You 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.</p>
<p>You now need to export the public key so we can tell the patcher about it.
You can do this with the following command (again as your normal user):</p>
<pre class="literal-block">
% gpg --export "email@address" > /tmp/exported_key
</pre>
<p>And now we can add your key to the <tt class="docutils literal"><span class="pre">allowed_keys</span></tt>:</p>
<pre class="literal-block">
(as root)> gpg --keyring /var/lib/darcs/repos/myproject/allowed_keys \
--no-default-keyring --import /tmp/exported_key
</pre>
<p>You can repeat this process any number of times to authorize multiple users
to send patches to the repository.</p>
<p>You should now be able to send a patch to the repository by running as your
normal user, in a working copy of the repository:</p>
<pre class="literal-block">
% darcs send --sign http://your.computer/repos/myproject
</pre>
<p>You may want to add "send sign" to the file <tt class="docutils literal"><span class="pre">_darcs/prefs/defaults</span></tt>
so that you won't need to type <tt class="docutils literal"><span class="pre">--sign</span></tt> every time you want to
send...</p>
<p>If your gpg key is protected by a passphrase, then executing <tt class="docutils literal"><span class="pre">send</span></tt>
with the <tt class="docutils literal"><span class="pre">--sign</span></tt> option might give you the following error:</p>
<pre class="literal-block">
darcs failed: Error running external program 'gpg'
</pre>
<p>The most likely cause of this error is that you have a misconfigured
gpg that tries to automatically use a non-existent gpg-agent
program. GnuPG will still work without gpg-agent when you try to sign
or encrypt your data with a passphrase protected key. However, it will
exit with an error code 2 (<tt class="docutils literal"><span class="pre">ENOENT</span></tt>) causing <tt class="docutils literal"><span class="pre">darcs</span></tt> to
fail. To fix this, you will need to edit your <tt class="docutils literal"><span class="pre">~/.gnupg/gpg.conf</span></tt>
file and comment out or remove the line that says:</p>
<pre class="literal-block">
use-agent
</pre>
<p class="last">If after commenting out or removing the <tt class="docutils literal"><span class="pre">use-agent</span></tt> line in your
gpg configuration file you still get the same error, then you probably
have a modified GnuPG with use-agent as a hard-coded option. In that
case, you should change <tt class="docutils literal"><span class="pre">use-agent</span></tt> to <tt class="docutils literal"><span class="pre">no-use-agent</span></tt> to
disable it explicitly.</p>
</dd>
<dt>Setting up a sendable repository using procmail</dt>
<dd><p class="first">If you don't have root access on your machine, or perhaps simply don't want
to bother creating a separate user, you can set up a darcs repository using
procmail to filter your mail. I will assume that you already use procmail
to filter your email. If not, you will need to read up on it, or perhaps
should use a different method for routing the email to darcs.</p>
<p>To begin with, you must configure your repository so that a darcs send to
your repository will know where to send the email. Do this by creating a
file in <tt class="docutils literal"><span class="pre">/path/to/your/repo/_darcs/prefs</span></tt> called <tt class="docutils literal"><span class="pre">email</span></tt>
containing your email address. As a trick (to be explained below), we will
create the email address with "darcs repo" as your name, in an email
address of the form "David Roundy $<<a class="reference external" href="mailto:$droundy@abridgegame.org$">$droundy@abridgegame.org$</a>>$."</p>
<pre class="literal-block">
% echo 'my darcs repo <user@host.com>' \
> /path/to/your/repo/_darcs/prefs/email
</pre>
<p>The next step is to set up a gnupg keyring containing the public keys of
people authorized to send to your repository. Here I'll give a second way of
going about this (see above for the first). This time I'll assume you
want to give me write access to your repository. You can do this by:</p>
<pre class="literal-block">
gpg --no-default-keyring \
--keyring /path/to/the/allowed_keys --recv-keys D3D5BCEC
</pre>
<p>This works because "D3D5BCEC" is the ID of my gpg key, and I have
uploaded my key to the gpg keyservers. Actually, this also requires that
you have configured gpg to access a valid keyserver. You can, of course,
repeat this command for all keys you want to allow access to.</p>
<p>Finally, we add a few lines to your <tt class="docutils literal"><span class="pre">.procmailrc</span></tt>:</p>
<pre class="literal-block">
:0
* ^TOmy darcs repo
|(umask 022; darcs apply --reply user@host.com \
--repodir /path/to/your/repo --verify /path/to/the/allowed_keys)
</pre>
<p>The purpose for the "my darcs repo" trick is partially to make it easier
to recognize patches sent to the repository, but is even more crucial to
avoid nasty bounce loops by making the <tt class="docutils literal"><span class="pre">--reply</span></tt> option have an email
address that won't go back to the repository. This means that unsigned
patches that are sent to your repository will be forwarded to your ordinary
email.</p>
<p class="last">Like most mail-processing programs, Procmail by default sets a tight umask.
However, this will prevent the repository from remaining world-readable;
thus, the "umask 022" is required to relax the umask.
(Alternatively, you could set Procmail's global <tt class="docutils literal"><span class="pre">UMASK</span></tt> variable
to a more suitable value.)</p>
</dd>
<dt>Checking if your e-mail patch was applied</dt>
<dd><p class="first">After sending a patch with <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">send</span></tt>, you may not receive any feedback,
even if the patch is applied. You can confirm whether or not your patch was applied
to the remote repository by pointing <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">changes</span></tt> at a remote repository:</p>
<pre class="literal-block">
darcs changes --last=10 --repo=http://darcs.net/
</pre>
<p class="last">That shows you the last 10 changes in the remote repository. You can adjust the options given
to <tt class="docutils literal"><span class="pre">changes</span></tt> if a more advanced query is needed.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="reducing-disk-space-usage">
<h2><a class="toc-backref" href="#id44">Reducing disk space usage</a></h2>
<p id="disk-usage">A Darcs repository contains the patches that Darcs uses to store
history, the working directory, and a <em>pristine tree</em> (a copy of
the working directory files with no local modifications). For large
repositories, this can add up to a fair amount of disk usage.</p>
<p>There are two techniques that can be used to reduce the amount of
space used by Darcs repositories: linking and using no pristine tree.
The former can be used on any repository; the latter is only suitable
in special circumstances, as it makes some operations much slower.</p>
<div class="section" id="linking-between-repositories">
<h3>Linking between repositories</h3>
<p>A number of filesystems support <em>linking</em> files, sharing a
single file data between different directories. Under some
circumstances, when repositories are very similar (typically because
they represent different branches of the same piece of software),
Darcs will use linking to avoid storing the same file multiple times.</p>
<p>Whenever you invoke <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt> to copy a repository from a local
filesystem onto the same filesystem, Darcs will link patches whenever
possible.</p>
<p>In order to save time, <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt> does not link pristine trees
even when individual files are identical. Additionally, as you pull
patches into trees, patches will become unlinked. This will result in
a lot of wasted space if two repositories have been living for a long
time but are similar. In such a case, you should <em>relink</em> files
between the two repositories.</p>
<p>Relinking is an asymmetric operation: you relink one repository (to
which you must have write access) to another repository, called the
<em>sibling</em>. This is done with <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">optimize</span> <span class="pre">--relink</span></tt>, with
--the <tt class="docutils literal"><span class="pre">--sibling</span></tt> flag specifying the sibling.</p>
<pre class="literal-block">
$ cd /var/repos/darcs.net
$ darcs optimize --relink --sibling /var/repos/darcs
</pre>
<p>The <tt class="docutils literal"><span class="pre">--sibling</span></tt> flag can be repeated multiple times, in which
case Darcs will try to find a file to link to in all of the siblings.
If a default repository is defined, Darcs will try, as a last resort,
to link against the default repository.</p>
<p>Additional space savings can be achieved by relinking files in the
pristine tree (see below) by using the <tt class="docutils literal"><span class="pre">--relink-pristine</span></tt> flag.
However, doing this prevents Darcs from having precise timestamps on
the pristine files, which carries a moderate performance penalty.</p>
</div>
<div class="section" id="alternate-formats-for-the-pristine-tree">
<h3>Alternate formats for the pristine tree</h3>
<p>By default, every Darcs repository contains a complete copy of the
<em>pristine tree</em>, the working tree as it would be if there were no
local edits. By avoiding the need to consult a possibly large number
of patches just to find out if a file is modified, the pristine tree
makes a lot of operations much faster than they would otherwise be.</p>
<p>Under some circumstances, keeping a whole pristine tree is not
desirable. This is the case when preparing a repository to back up,
when publishing a repository on a public web server with limited
space, or when storing a repository on floppies or small USB keys. In
such cases, it is possible to use a repository with no pristine tree.</p>
<p>Darcs automatically recognizes a repository with no pristine
tree. In order to create such a tree, specify the
<tt class="docutils literal"><span class="pre">--no-pristine-tree</span></tt> flag to <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">initialize</span></tt> or
<tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt>. There is currently no way to switch an existing
repository to use no pristine tree.</p>
<p>The support for <tt class="docutils literal"><span class="pre">--no-pristine-tree</span></tt> repositories is fairly new,
and has not been extensively optimized yet. Please let us know if you
use this functionality, and which operations you find are too slow.</p>
<p>% Copyright (C) 2004 David Roundy</p>
<p>% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.</p>
<p>% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
% GNU General Public License for more details.</p>
<p>% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software Foundation,
% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.</p>
</div>
</div>
</div>
<div class="section" id="configuring-darcs">
<h1><a class="toc-backref" href="#id45">Configuring darcs</a></h1>
<p id="configuring">There are several ways you can adjust darcs' behavior to suit your needs.
The first is to edit files in the <tt class="docutils literal"><span class="pre">_darcs/prefs/</span></tt> directory of a
repository. Such configuration only applies when working with that
repository. To configure darcs on a per-user rather than per-repository
basis (but with essentially the same methods), you can edit (or create)
files in the <tt class="docutils literal"><span class="pre">~/.darcs/</span></tt> directory. Finally, the behavior of some
darcs commands can be modified by setting appropriate environment
variables.</p>
<p>input{Darcs/Repository/Prefs.lhs}</p>
<p>input{Darcs/Repository/Motd.lhs}</p>
<div class="section" id="environment-variables">
<h2><a class="toc-backref" href="#id46">Environment variables</a></h2>
<p>There are a few environment variables whose contents affect darcs'
behavior. Here is a quick list of all the variables and their
documentation in the rest of the manual:</p>
<ul class="simple">
<li><a class="reference internal" href="#darcs-editor">DARCS_EDITOR</a>, EDITOR, VISUAL</li>
<li><a class="reference internal" href="#darcs-pager">DARCS_PAGER</a>, PAGER</li>
<li><a class="reference internal" href="#home">HOME</a></li>
<li><a class="reference internal" href="#term">TERM</a></li>
<li><a href="#id85"><span class="problematic" id="id86">DARCS_EMAIL_</span></a>, EMAIL</li>
<li><a class="reference internal" href="#darcs-apply-foo">DARCS_APPLY_FOO</a>, DARCS_GET_FOO, DARCS_MGET_FOO</li>
<li><a class="reference internal" href="#darcs-mgetmax">DARCS_MGETMAX</a></li>
<li><a class="reference internal" href="#darcs-proxyuserpwd">DARCS_PROXYUSERPWD</a></li>
<li><a class="reference internal" href="#darcs-wget">DARCS_WGET</a></li>
<li><a class="reference internal" href="#darcs-ssh">DARCS_SSH</a></li>
<li><a class="reference internal" href="#darcs-scp">DARCS_SCP</a></li>
<li><a class="reference internal" href="#darcs-sftp">DARCS_SFTP</a></li>
<li><a class="reference internal" href="#ssh-port">SSH_PORT</a></li>
<li>DARCS_ALTERNATIVE_COLOR, <a class="reference internal" href="#darcs-always-color">DARCS_ALWAYS_COLOR</a>, DARCS_DONT_COLOR</li>
<li><a class="reference internal" href="#darcs-do-color-lines">DARCS_DO_COLOR_LINES</a></li>
<li><a class="reference internal" href="#darcs-dont-escape-trailing-cr">DARCS_DONT_ESCAPE_TRAILING_CR</a>, DARCS_DONT_ESCAPE_TRAILING_SPACES</li>
<li><a class="reference internal" href="#darcs-dont-escape-8bit">DARCS_DONT_ESCAPE_8BIT</a>,
DARCS_DONT_ESCAPE_ANYTHING,
DARCS_DONT_ESCAPE_ISPRINT,
DARCS_ESCAPE_EXTRA,
DARCS_DONT_ESCAPE_EXTRA</li>
</ul>
</div>
<div class="section" id="general-purpose-variables">
<h2><a class="toc-backref" href="#id47">General-purpose variables</a></h2>
<dl class="docutils" id="darcs-editor">
<dt>DARCS_EDITOR</dt>
<dd>When pulling up an editor (for example, when adding a long comment in
record), darcs uses the contents of DARCS_EDITOR if it is defined. If
not, it tries the contents of VISUAL, and if that isn't defined (or fails
for some reason), it tries EDITOR. If none of those environment variables
are defined, darcs tries <tt class="docutils literal"><span class="pre">vi</span></tt>, <tt class="docutils literal"><span class="pre">emacs</span></tt>, <tt class="docutils literal"><span class="pre">emacs</span> <span class="pre">-nw</span></tt> and
<tt class="docutils literal"><span class="pre">nano</span></tt> in that order.</dd>
</dl>
<dl class="docutils" id="darcs-pager">
<dt>DARCS_PAGER</dt>
<dd>When using a pager for displaying a patch, darcs uses the contents of
DARCS_PAGER if it is defined. If not, it tries the contents of PAGER
and then <tt class="docutils literal"><span class="pre">less</span></tt>.</dd>
</dl>
<dl class="docutils" id="darcs-tmpdir">
<dt>DARCS_TMPDIR</dt>
<dd><p class="first">If the environment variable DARCS_TMPDIR is defined, darcs will use that
directory for its temporaries. Otherwise it will use TMPDIR, if that is
defined, and if not that then <tt class="docutils literal"><span class="pre">/tmp</span></tt> and if <tt class="docutils literal"><span class="pre">/tmp</span></tt> doesn't exist,
it'll put the temporaries in <tt class="docutils literal"><span class="pre">_darcs</span></tt>.</p>
<p class="last">This is very helpful, for example, when recording with a test suite that
uses MPI, in which case using <tt class="docutils literal"><span class="pre">/tmp</span></tt> to hold the test copy is no good,
as <tt class="docutils literal"><span class="pre">/tmp</span></tt> isn't shared over NFS and thus the <tt class="docutils literal"><span class="pre">mpirun</span></tt> call will
fail, since the binary isn't present on the compute nodes.</p>
</dd>
</dl>
<dl class="docutils" id="darcs-keep-tmpdir">
<dt>DARCS_KEEP_TMPDIR</dt>
<dd>If the environment variable DARCS_KEEP_TMPDIR is defined, darcs will
not remove temprary directories.</dd>
</dl>
<p>This can be useful for darcs debugging.</p>
<dl class="docutils" id="home">
<dt>HOME</dt>
<dd>HOME is used to find the per-user prefs directory, which is located at
<tt class="docutils literal"><span class="pre">$HOME/.darcs</span></tt>.</dd>
</dl>
<p>%$ this dollar is a comment to make my emacs leave math mode... (stupid
% emacs)</p>
<dl class="docutils" id="term">
<dt>TERM</dt>
<dd>If darcs is compiled with libcurses support and support for color output,
it uses the environment variable TERM to decide whether or not color is
supported on the output terminal.</dd>
</dl>
</div>
<div class="section" id="remote-repositories">
<h2><a class="toc-backref" href="#id48">Remote repositories</a></h2>
<dl class="docutils" id="ssh-port">
<dt>SSH_PORT</dt>
<dd>When using ssh, if the SSH_PORT environment variable is defined, darcs will
use that port rather than the default ssh port (which is 22).</dd>
</dl>
<dl class="docutils" id="darcs-ssh">
<dt>DARCS_SSH</dt>
<dd>The DARCS_SSH environment variable defines the command that darcs will use
when asked to run ssh. This command is <em>not</em> interpreted by a shell,
so you cannot use shell metacharacters, and the first word in the command
must be the name of an executable located in your path.</dd>
</dl>
<dl class="docutils" id="darcs-sftp">
<span id="darcs-scp"></span><dt>DARCS_SCP and DARCS_SFTP</dt>
<dd>The DARCS_SCP and DARCS_SFTP environment variables define the
commands that darcs will use when asked to run scp or sftp. Darcs uses
scp and sftp to access repositories whose address is of the
form <tt class="docutils literal"><span class="pre">user@foo.org:foo</span></tt> or <tt class="docutils literal"><span class="pre">foo.org:foo</span></tt>. Darcs will use
scp to copy single files (e.g. repository meta-information), and sftp
to copy multiple files in batches (e.g. patches). These commands are
<em>not</em> interpreted by a shell, so you cannot use shell
metacharacters, and the first word in the command must be the name of
an executable located in your path. By default, <tt class="docutils literal"><span class="pre">scp</span></tt> and <tt class="docutils literal"><span class="pre">sftp</span></tt>
are used. When you can use sftp, but not scp (e.g. some ISP web sites), it
works to set DARCS_SCP to "sftp". The other way around does not work, i.e.
DARCS_FTP must reference an sftp program, not scp.</dd>
</dl>
<dl class="docutils" id="darcs-proxyuserpwd">
<dt>DARCS_PROXYUSERPWD</dt>
<dd>This environment variable allows DARCS and libcurl to access remote repositories
via a password-protected HTTP proxy. The proxy itself is specified with the standard
environment variable for this purpose, namely 'http_proxy'. The DARCS_PROXYUSERPWD
environment variable specifies the proxy username and password. It must be given in
the form <em>username:password</em>.</dd>
</dl>
<dl class="docutils" id="darcs-apply-foo">
<dt>DARCS_GET_FOO, DARCS_MGET_FOO and DARCS_APPLY_FOO</dt>
<dd>When trying to access a repository with a URL beginning foo://,
darcs will invoke the program specified by the DARCS_GET_FOO
environment variable (if defined) to download each file, and the
command specified by the DARCS_APPLY_FOO environment variable (if
defined) when pushing to a foo:// URL.</dd>
</dl>
<p>This method overrides all other ways of getting <tt class="docutils literal"><span class="pre">foo://xxx</span></tt> URLs.</p>
<p>Note that each command should be constructed so that it sends the downloaded
content to STDOUT, and the next argument to it should be the URL. Here are some
examples that should work for DARCS_GET_HTTP:</p>
<pre class="literal-block">
fetch -q -o -
curl -s -f
lynx -source
wget -q -O -
</pre>
<p>If set, DARCS_MGET_FOO
will be used to fetch many files from a single repository simultaneously.
Replace FOO and foo as appropriate to handle other URL schemes.
These commands are <em>not</em> interpreted by a shell, so you cannot
use shell metacharacters, and the first word in the command must
be the name of an executable located in your path. The GET command
will be called with a URL for each file. The MGET command will be
invoked with a number of URLs and is expected to download the files
to the current directory, preserving the file name but not the path.
The APPLY command will be called with a darcs patchfile piped into
its standard input. Example:</p>
<pre class="literal-block">
wget -q
</pre>
<dl class="docutils" id="darcs-mgetmax">
<dt>DARCS_MGETMAX</dt>
<dd>When invoking a DARCS_MGET_FOO command, darcs will limit the
number of URLs presented to the command to the value of this variable,
if set, or 200.</dd>
</dl>
<dl class="docutils" id="darcs-wget">
<dt>DARCS_WGET</dt>
<dd><p class="first">This is a very old option that is only used if libcurl is not compiled
in and one of the DARCS_GET_FOO is not used. Using one of those
is recommended instead.</p>
<p>The DARCS_WGET environment variable defines the command that darcs
will use to fetch all URLs for remote repositories. The first word in
the command must be the name of an executable located in your path.
Extra arguments can be included as well, such as:</p>
<pre class="last literal-block">
wget -q
Darcs will append ``-i`` to the argument list, which it uses to provide a
list of URLS to download. This allows wget to download multiple patches at the
same time. It's possible to use another command besides ``wget`` with this
environment variable, but it must support the ``-i`` option in the same way.
</pre>
</dd>
</dl>
<p>These commands are <em>not</em> interpreted by a shell, so you cannot use shell
meta-characters.</p>
</div>
<div class="section" id="highlighted-output">
<h2><a class="toc-backref" href="#id49">Highlighted output</a></h2>
<p id="darcs-dont-escape-trailing-cr"><span id="darcs-do-color-lines"></span><span id="darcs-always-color"></span>If the terminal understands ANSI color escape sequences,
darcs will highlight certain keywords and delimiters when printing patches.
This can be turned off by setting the environment variable DARCS_DONT_COLOR to 1.
If you use a pager that happens to understand ANSI colors, like <tt class="docutils literal"><span class="pre">less</span> <span class="pre">-R</span></tt>,
darcs can be forced always to highlight the output
by setting DARCS_ALWAYS_COLOR to 1.
If you can't see colors you can set DARCS_ALTERNATIVE_COLOR to 1,
and darcs will use ANSI codes for bold and reverse video instead of colors.
In addition, there is an extra-colorful mode, which is not enabled by
default, which can be activated with DARCS_DO_COLOR_LINES.</p>
<p>By default darcs will escape (by highlighting if possible) any kind of spaces at the end of lines
when showing patch contents.
If you don't want this you can turn it off by setting
DARCS_DONT_ESCAPE_TRAILING_SPACES to 1.
A special case exists for only carriage returns:
DARCS_DONT_ESCAPE_TRAILING_CR.</p>
</div>
<div class="section" id="character-escaping-and-non-ascii-character-encodings">
<h2><a class="toc-backref" href="#id50">Character escaping and non-ASCII character encodings</a></h2>
<p id="darcs-dont-escape-8bit">Darcs needs to escape certain characters when printing patch contents to a terminal.
Characters like <em>backspace</em> can otherwise hide patch content from the user,
and other character sequences can even in some cases redirect commands to the shell
if the terminal allows it.</p>
<p>By default darcs will only allow printable 7-bit ASCII characters (including space),
and the two control characters <em>tab</em> and <em>newline</em>.
(See the last paragraph in this section for a way to tailor this behavior.)
All other octets are printed in quoted form (as <tt class="docutils literal"><span class="pre">^<control</span> <span class="pre">letter></span></tt> or
<tt class="docutils literal"><span class="pre">???FIXME???<hex</span> <span class="pre">code></span></tt>).</p>
<p>Darcs has some limited support for locales.
If the system's locale is a single-byte character encoding,
like the Latin encodings,
you can set the environment variable DARCS_DONT_ESCAPE_ISPRINT to 1
and darcs will display all the printables in the current system locale
instead of just the ASCII ones.
NOTE: This curently does not work on some architectures if darcs is
compiled with GHC 6.4. Some non-ASCII control characters might be printed
and can possibly spoof the terminal.</p>
<p>For multi-byte character encodings things are less smooth.
UTF-8 will work if you set DARCS_DONT_ESCAPE_8BIT to 1,
but non-printables outside the 7-bit ASCII range are no longer escaped.
E.g., the extra control characters from Latin-1
might leave your terminal at the mercy of the patch contents.
Space characters outside the 7-bit ASCII range are no longer recognized
and will not be properly escaped at line endings.</p>
<p>As a last resort you can set DARCS_DONT_ESCAPE_ANYTHING to 1.
Then everything that doesn't flip code sets should work,
and so will all the bells and whistles in your terminal.
This environment variable can also be handy
if you pipe the output to a pager or external filter
that knows better than darcs how to handle your encoding.
Note that <em>all</em> escaping,
including the special escaping of any line ending spaces,
will be turned off by this setting.</p>
<p>There are two environment variables you can set
to explicitly tell darcs to not escape or escape octets.
They are
DARCS_DONT_ESCAPE_EXTRA and DARCS_ESCAPE_EXTRA.
Their values should be strings consisting of the verbatim octets in question.
The do-escapes take precedence over the dont-escapes.
Space characters are still escaped at line endings though.
The special environment variable DARCS_DONT_ESCAPE_TRAILING_CR
turns off escaping of carriage return last on the line (DOS style).</p>
<p>% This file (unlike the rest of darcs) is in the public domain.</p>
</div>
</div>
<div class="section" id="best-practices">
<h1><a class="toc-backref" href="#id51">Best practices</a></h1>
<div class="section" id="id4">
<h2><a class="toc-backref" href="#id52">Introduction</a></h2>
<p>This chapter is intended to review various scenarios and describe in each
case effective ways of using darcs. There is no one "best practice", and
darcs is a sufficiently low-level tool that there are many high-level ways
one can use it, which can be confusing to new users. The plan (and hope)
is that various users will contribute here describing how they use darcs in
different environments. However, this is not a wiki, and contributions
will be edited and reviewed for consistency and wisdom.</p>
</div>
<div class="section" id="creating-patches">
<h2><a class="toc-backref" href="#id53">Creating patches</a></h2>
<p>This section will lay down the concepts around patch creation.
The aim is to develop a way of thinking
that corresponds well to how darcs is behaving
--- even in complicated situations.</p>
<p>In a single darcs repository you can think of two "versions" of the source tree.
They are called the <em>working</em> and <em>pristine</em> trees.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Working:</th><td class="field-body">is your normal source tree, with or without darcs alongside.
The only thing that makes it part of a darcs repository is the
<tt class="docutils literal"><span class="pre">_darcs</span></tt> directory in its root.</td>
</tr>
<tr class="field"><th class="field-name">Pristine:</th><td class="field-body">is the recorded state of the source tree.
The pristine tree is constructed from groups of changes,
called <em>patches/</em> (some other version control systems use the
term <em>changeset/</em> instead of <em>patch/</em>). <a class="footnote-reference" href="#id6" id="id5">[2]</a>
Darcs will create and store these patches
based on the changes you make in <em>working</em>.</td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[2]</a></td><td>If you look inside _darcs you will find files or directories named
<tt class="docutils literal"><span class="pre">patches</span></tt> and <tt class="docutils literal"><span class="pre">inventories</span></tt>, which store all the patches
ever recorded. If the repository holds a cached pristine tree, it
is stored in a directory called <tt class="docutils literal"><span class="pre">pristine</span></tt> or <tt class="docutils literal"><span class="pre">current/</span></tt>;
otherwise, the fact that there is no pristine tree is marked
by the presence of a file called <tt class="docutils literal"><span class="pre">pristine.none</span></tt> or
<tt class="docutils literal"><span class="pre">current.none</span></tt>.</td></tr>
</tbody>
</table>
<div class="section" id="changes">
<h3>Changes</h3>
<p>If <em>working</em> and <em>pristine</em> are the same,
there are "no changes" in the repository.
Changes can be introduced (or removed) by editing the files in <em>working</em>.
They can also be caused by darcs commands,
which can modify <em>both</em> <em>working</em> and <em>pristine</em>.
It is important to understand for each darcs command
how it modifies <em>working</em>, <em>pristine</em> or both of them.</p>
<p><tt class="docutils literal"><span class="pre">whatsnew</span></tt> (as well as <tt class="docutils literal"><span class="pre">diff</span></tt>) can show
the difference between <em>working</em> and <em>pristine</em> to you.
It will be shown as a difference in <em>working</em>.
In advanced cases it need <em>not</em> be <em>working</em> that has changed;
it can just as well have been <em>pristine</em>, or both.
The important thing is the difference and what darcs can do with it.</p>
</div>
<div class="section" id="keeping-or-discarding-changes">
<h3>Keeping or discarding changes</h3>
<p>If you have a difference in <em>working</em>, you do two things
with it: <tt class="docutils literal"><span class="pre">record</span></tt> it to keep it, or <tt class="docutils literal"><span class="pre">revert</span></tt> it to lose the changes. <a class="footnote-reference" href="#id8" id="id7">[3]</a></p>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id7">[3]</a></td><td>Revert can undo precious work in a blink.
To protect you from great grief,
the discarded changes are saved temporarily
so the latest revert can be undone with unrevert.</td></tr>
</tbody>
</table>
<p>If you have a difference between <em>working</em> and <em>pristine</em>
---for example after editing some files in <em>working*—
``whatsnew`` will show some "unrecorded changes".
To save these changes, use ``record``.
It will create a new patch in *pristine</em> with the same changes,
so <em>working</em> and <em>pristine</em> are no longer different.
To instead undo the changes in <em>working</em>, use <tt class="docutils literal"><span class="pre">revert</span></tt>.
It will modify the files in <em>working</em> to be the same as in <em>pristine</em>
(where the changes do not exist).</p>
</div>
<div class="section" id="unrecording-changes">
<h3>Unrecording changes</h3>
<p><tt class="docutils literal"><span class="pre">unrecord</span></tt> is a command meant to be run only in private
repositories. Its intended purpose is to allow developers the flexibility
to undo patches that haven't been distributed yet.</p>
<p>However, darcs does not prevent you from unrecording a patch that
has been copied to another repository. Be aware of this danger!</p>
<p>If you <tt class="docutils literal"><span class="pre">unrecord</span></tt> a patch, that patch will be deleted from <em>pristine</em>.
This will cause <em>working</em> to be different from <em>pristine</em>,
and <tt class="docutils literal"><span class="pre">whatsnew</span></tt> to report unrecorded changes.
The difference will be the same as just before that patch was <tt class="docutils literal"><span class="pre">record``ed.</span>
<span class="pre">Think</span> <span class="pre">about</span> <span class="pre">it.</span>
<span class="pre">``record</span></tt> examines what's different with <em>working</em>
and constructs a patch with the same changes in <em>pristine</em>
so they are no longer different.
<tt class="docutils literal"><span class="pre">unrecord</span></tt> deletes this patch;
the changes in <em>pristine</em> disappear and the difference is back.</p>
<p>If the recorded changes included an error,
the resulting flawed patch can be unrecorded.
When the changes have been fixed,
they can be recorded again as a new—hopefully flawless—patch.</p>
<p>If the whole change was wrong it can be discarded from <em>working</em> too,
with <tt class="docutils literal"><span class="pre">revert</span></tt>.
<tt class="docutils literal"><span class="pre">revert</span></tt> will update <em>working</em> to the state of <em>pristine</em>,
in which the changes do no longer exist after the patch was deleted.</p>
<p>Keep in mind that the patches are your history,
so deleting them with <tt class="docutils literal"><span class="pre">unrecord</span></tt> makes it impossible to track
what changes you <em>really</em> made.
Redoing the patches is how you "cover the tracks".
On the other hand,
it can be a very convenient way to manage and organize changes
while you try them out in your private repository.
When all is ready for shipping,
the changes can be reorganized in what seems as useful and impressive patches.
Use it with care.</p>
<p>All patches are global,
so don't <em>ever</em> replace an already "shipped" patch in this way!
If an erroneous patch is deleted and replaced with a better one,
you have to replace it in <em>all</em> repositories that have a copy of it.
This may not be feasible, unless it's all private repositories.
If other developers have already made patches or tags in their repositories
that depend on the old patch, things will get complicated.</p>
</div>
<div class="section" id="special-patches-and-pending">
<h3>Special patches and pending</h3>
<p>The patches described in the previous sections have mostly been hunks.
A <em>hunk</em> is one of darcs' primitive patch types,
and it is used to remove old lines and/or insert new lines.
There are other types of primitive patches,
such as <em>adddir</em> and <em>addfile</em>
which add new directories and files,
and <em>replace</em>
which does a search-and-replace on tokens in files.</p>
<p>Hunks are always calculated in place with a diff algorithm
just before <tt class="docutils literal"><span class="pre">whatsnew</span></tt> or <tt class="docutils literal"><span class="pre">record</span></tt>.
But other types of primitive patches need to be explicitly created
with a darcs command.
They are kept in <em>pending</em> <a class="footnote-reference" href="#id10" id="id9">[4]</a>
until they are either recorded or reverted.</p>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9">[4]</a></td><td>In the file <tt class="docutils literal"><span class="pre">_darcs/patches/pending</span></tt>.</td></tr>
</tbody>
</table>
<p><em>Pending</em> can be thought of as a special extension of <em>working</em>.
When you issue, e.g., a darcs <tt class="docutils literal"><span class="pre">replace</span></tt> command,
the replace is performed on the files in <em>working</em>
and at the same time a replace patch is put in <em>pending</em>.
Patches in <em>pending</em> describe special changes made in <em>working</em>.
The diff algorithm will fictively apply these changes to <em>pristine</em>
before it compares it to <em>working</em>,
so all lines in <em>working</em> that are changed by a <tt class="docutils literal"><span class="pre">replace</span></tt> command
will also be changed in <em>pending*$+$*pristine</em>
when the hunks are calculated.
That's why no hunks with the replaced lines will be shown by <tt class="docutils literal"><span class="pre">whatsnew</span></tt>;
it only shows the replace patch in <em>pending</em> responsible for the change.</p>
<p>If a special patch is recorded, it will simply be moved to <em>pristine</em>.
If it is instead reverted, it will be deleted from <em>pending</em>
and the accompanying change will be removed from <em>working</em>.</p>
<p>Note that reverting a patch in pending is <em>not</em> the same as
simply removing it from pending.
It actually applies the inverse of the change to <em>working</em>.
Most notable is that reverting an addfile patch
will delete the file in <em>working</em> (the inverse of adding it).
So if you add the wrong file to darcs by mistake,
<em>don't</em> <tt class="docutils literal"><span class="pre">revert</span></tt> the addfile.
Instead use <tt class="docutils literal"><span class="pre">remove</span></tt>, which cancels out the addfile in pending.</p>
</div>
</div>
<div class="section" id="using-patches-still-basics">
<h2><a class="toc-backref" href="#id54">Using patches % still basics</a></h2>
<p>This section will lay down the concepts around patch distribution and branches.
The aim is to develop a way of thinking
that corresponds well to how darcs is behaving
--- even in complicated situations.</p>
<p>A repository is a collection of patches.
Patches have no defined order,
but patches can have dependencies on other patches.
Patches can be added to a repository in any order
as long as all patches depended upon are there.
Patches can be removed from a repository in any order,
as long as no remaining patches depend on them.</p>
<p>Repositories can be cloned to create branches.
Patches created in different branches may conflict.
A conflict is a valid state of a repository.
A conflict makes the working tree ambiguous until the conflict is resolved.</p>
<div class="section" id="dependencies">
<h3>Dependencies</h3>
<p>There are two kinds of dependencies:
implicit dependencies and explicit dependencies.</p>
<p>Implicit dependencies is the far most common kind.
These are calculated automatically by darcs.
If a patch removes a file or a line of code,
it will have to depend on the patch that added that file or line of code. <a class="footnote-reference" href="#id12" id="id11">[5]</a>
If a patch adds a line of code,
it will usually have to depend on the patch or patches that added the adjacent lines.</p>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id11">[5]</a></td><td>Actually it doesn't have to—in theory—,
but in practice it's hard to create "negative" files or lines in the working tree.
See the chapter about Theory of patches for other constraints.</td></tr>
</tbody>
</table>
<p>Explicit dependencies can be created if you give the <tt class="docutils literal"><span class="pre">--ask-deps</span></tt> option to <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">record</span></tt>.
This is good for assuring that logical dependencies hold between patches.
It can also be used to group patches—
a patch with explicit dependencies doesn't need to change anything—
and pulling the patch also pulls all patches it was made to depend on.</p>
</div>
<div class="section" id="branches-just-normal-repositories">
<h3>Branches: just normal repositories</h3>
<p>Darcs does not have branches—it doesn't need to.
Every repository can be used as a branch.
This means that any two repositories are "branches" in darcs,
but it is not of much use unless they have a large portion of patches in common.
If they are different projects they will have nothing in common,
but darcs may still very well be able to merge them,
although the result probably is nonsense.
Therefore the word "branch" isn't a technical term in darcs;
it's just the way we think of one repository in relation to another.</p>
<p>Branches are <em>very</em> useful in darcs.
They are in fact <em>necessary</em> if you want to do more than only simple work.
When you <tt class="docutils literal"><span class="pre">get</span></tt> someone's repository from the Internet,
you are actually creating a branch of it.
It may first seem inefficient (or if you come from CVS—frightening),
not to say plain awkward.
But darcs is designed this way, and it has means to make it efficient.
The answer to many questions about how to do a thing with darcs is: "use a branch".
It is a simple and elegant solution with great power and flexibility,
which contributes to darcs' uncomplicated user interface.</p>
<p>You create new branches (i.e., clone repositories)
with the <tt class="docutils literal"><span class="pre">get</span></tt> and <tt class="docutils literal"><span class="pre">put</span></tt> commands.</p>
</div>
<div class="section" id="moving-patches-around-no-versions">
<h3>Moving patches around—no versions</h3>
<p>Patches are global, and a copy of a patch either is or is not present in a branch.
This way you can rig a branch almost any way you like,
as long as dependencies are fulfilled—
darcs <em>won't</em> let you break dependencies.
If you suspect a certain feature from some time ago introduced a bug,
you can remove the patch/patches that adds the feature,
and try without it. <a class="footnote-reference" href="#id14" id="id13">[6]</a></p>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id13">[6]</a></td><td>darcs even has a special command, <tt class="docutils literal"><span class="pre">trackdown</span></tt>
that automatically removes patches
until a specified test no longer fails.</td></tr>
</tbody>
</table>
<p>Patches are added to a repository with <tt class="docutils literal"><span class="pre">pull</span></tt>
and removed from the repositories with <tt class="docutils literal"><span class="pre">obliterate</span></tt>.
Don't confuse these two commands with <tt class="docutils literal"><span class="pre">record</span></tt> and <tt class="docutils literal"><span class="pre">unrecord</span></tt>,
which constructs and deconstructs patches.</p>
<p>It is important not to lose patches when (re)moving them around.
<tt class="docutils literal"><span class="pre">pull</span></tt> needs a source repository to copy the patch from,
whereas <tt class="docutils literal"><span class="pre">obliterate</span></tt> just erases the patch.
Beware that if you obliterate <em>all</em> copies of a patch
it is completely lost—forever.
Therefore you should work with branches when you obliterate patches.
The <tt class="docutils literal"><span class="pre">obliterate</span></tt> command can wisely be disabled in a dedicated main repository
by adding <tt class="docutils literal"><span class="pre">obliterate</span> <span class="pre">disable</span></tt> to the repository's defaults file.</p>
<p>For convenience, there is a <tt class="docutils literal"><span class="pre">push</span></tt> command.
It works like <tt class="docutils literal"><span class="pre">pull</span></tt> but in the other direction.
It also differs from <tt class="docutils literal"><span class="pre">pull</span></tt> in an important way:
it starts a second instance of darcs to apply the patch in the target repository,
even if it's on the same computer.
It can cause surprises if you have a "wrong" darcs in your PATH.</p>
</div>
<div class="section" id="tags-versions">
<h3>Tags—versions</h3>
<p>While <tt class="docutils literal"><span class="pre">pull</span></tt> and <tt class="docutils literal"><span class="pre">obliterate</span></tt> can be used to
construct different "versions" in a repository,
it is often desirable to name specific configurations of patches
so they can be identified and retrieved easily later.
This is how darcs implements what is usually known as versions.
The command for this is <tt class="docutils literal"><span class="pre">tag</span></tt>,
and it records a tag in the current repository.</p>
<p>A tag is just a patch, but it only contains explicit dependencies.
It will depend on all the patches in the current repository. <a class="footnote-reference" href="#id16" id="id15">[7]</a></p>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id15">[7]</a></td><td>It will omit patches already depended upon by other patches,
since they will be indirectly depended upon anyway.</td></tr>
</tbody>
</table>
<p>Darcs can recognize if a patch is as a tag;
tags are sometimes treated specially by darcs commands.</p>
<p>While traditional revision control systems tag versions in the time line history,
darcs lets you tag any configuration of patches at any time,
and pass the tags around between branches.</p>
<p>With the option <tt class="docutils literal"><span class="pre">--tag</span></tt> to <tt class="docutils literal"><span class="pre">get</span></tt> you can easily get
a named version in the repository
as a new branch.</p>
</div>
<div class="section" id="conflicts">
<h3>Conflicts</h3>
<p>This part of darcs becomes a bit complicated,
and the description given here is slightly simplified.</p>
<p>Conflicting patches are created when
you record changes to the same line in two different repositories.
Same line does <em>not</em> mean the same line number and file name,
but the same line added by a common depended-upon patch.</p>
<p>If you are using a darcs-2 repository (Section <a href="#id87"><span class="problematic" id="id88">initialize_</span></a>),
darcs does <em>not</em> consider two patches making the <em>same</em> change to be a
conflict, much in the same fashion as other version control systems.
(The caveat here is two non-identical patches with some identical
changes may conflict. For the most part, darcs should just do what you
expect).</p>
<p>A conflict <em>happens</em> when two conflicting patches meet in the same repository.
This is no problem for darcs; it can happily pull together just any patches.
But it is a problem for the files in <em>working</em> (and <em>pristine</em>).
The conflict can be thought of as
two patches telling darcs different things about what a file should look like.</p>
<p>Darcs escapes this problem
by ignoring those parts <a class="footnote-reference" href="#id18" id="id17">[8]</a>
of the patches that conflict.
They are ignored in <em>both</em> patches.
If patch A changes the line "FIXME" to "FIXED",
and patch B changes the same line to "DONE",
the two patches together will produce the line "FIXME".
Darcs doesn't care which one you pulled into the repository first,
you still get the same result when the conflicting patches meet.
All other changes made by A and B are performed as normal.</p>
<table class="docutils footnote" frame="void" id="id18" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id17">[8]</a></td><td>The primitive patches making up the total patch.</td></tr>
</tbody>
</table>
<p>Darcs can mark a conflict for you in <em>working</em>.
This is done with <tt class="docutils literal"><span class="pre">mark-conflicts</span></tt>.
Conflicts are marked such that both conflicting changes
are inserted with special delimiter lines around them.
Then you can merge the two changes by hand,
and remove the delimiters.</p>
<p>When you pull patches,
darcs automatically performs a <tt class="docutils literal"><span class="pre">mark-conflicts</span></tt> for you if a conflict happens.
You can remove the markup with <tt class="docutils literal"><span class="pre">revert</span></tt>,
Remember that the result will be the lines from
the previous version common to both conflicting patches.
The conflict marking can be redone again with <tt class="docutils literal"><span class="pre">mark-conflicts</span></tt>.</p>
<p>A special case is when a pulled patch conflicts with unrecorded changes in the repository.
The conflict will be automatically marked as usual,
but since the markup is <em>also</em> an unrecorded change,
it will get mixed in with your unrecorded changes.
There is no guarantee you can revert <em>only</em> the markup after this,
and <tt class="docutils literal"><span class="pre">resolve</span></tt> will not be able to redo this markup later if you remove it.
It is good practice to record important changes before pulling.</p>
<p><tt class="docutils literal"><span class="pre">mark-conflicts</span></tt> can't mark complicated conflicts.
In that case you'll have to use <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">diff</span></tt> and other commands
to understand what the conflict is all about.
If for example two conflicting patches create the same file,
<tt class="docutils literal"><span class="pre">mark-conflicts</span></tt> will pick just one of them,
and no delimiters are inserted.
So watch out if darcs tells you about a conflict.</p>
<p><tt class="docutils literal"><span class="pre">mark-conflicts</span></tt> can also be used to check for unresolved conflicts.
If there are none, darcs replies "No conflicts to resolve".
While <tt class="docutils literal"><span class="pre">pull</span></tt> reports when a conflict happens,
<tt class="docutils literal"><span class="pre">obliterate</span></tt> and <tt class="docutils literal"><span class="pre">get</span></tt> don't.</p>
</div>
<div class="section" id="resolving-conflicts">
<h3>Resolving conflicts</h3>
<p>A conflict is resolved
(not marked, as with the command <tt class="docutils literal"><span class="pre">mark-conflicts</span></tt>)
as soon as some new patch depends on the conflicting patches.
This will usually be the resolve patch you record after manually putting together the pieces
from the conflict markup produced by <tt class="docutils literal"><span class="pre">mark-conflicts</span></tt> (or <tt class="docutils literal"><span class="pre">pull</span></tt>).
But it can just as well be a tag.
So don't forget to fix conflicts before you accidently "resolve" them by recording other patches.</p>
<p>If the conflict is with one of your not-yet-published patches,
you may choose to amend that patch rather than creating a resolve patch.</p>
<p>If you want to back out and wait with the conflict,
you can <tt class="docutils literal"><span class="pre">obliterate</span></tt> the conflicting patch you just pulled.
Before you can do that you have to <tt class="docutils literal"><span class="pre">revert</span></tt> the conflict markups
that <tt class="docutils literal"><span class="pre">pull</span></tt> inserted when the conflict happened.</p>
</div>
</div>
<div class="section" id="enable-a-global-cache">
<h2><a class="toc-backref" href="#id55">Enable a Global Cache</a></h2>
<p>When working with darcs 2 it is recommended to enable a global cache, as
this is one of the biggest performance enhancing tools of darcs 2. The
global cache acts as a giant patch pool where darcs first looks for a
patch when grabbing new patches, thus you want it to be on the same file
system as your repositories. On file systems that support it, the
cached patches are going to be hardlinked (the patch is only stored
once, but represented in multiple places) across all of your
repositories.</p>
<p>To enable a Global Cache:</p>
<pre class="literal-block">
$ mkdir -p $HOME/.darcs/cache
$ echo cache:$HOME/.darcs/cache > $HOME/.darcs/sources
</pre>
<p>In Windows you can run just about the same commands from <tt class="docutils literal"><span class="pre">cmd.exe</span></tt>
(Command Prompt under Accessories):</p>
<pre class="literal-block">
> md %UserProfile%\.darcs\cache
> echo cache:%UserProfile%\.darcs\cache > %UserProfile%\.darcs\sources
</pre>
<p>There are some other advanced things you can do in <tt class="docutils literal"><span class="pre">_darcs/prefs/sources</span></tt>,
such as create per-repository caches, read-only caches and even set a
primary source repository above any used in a <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt> or
<tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">pull</span></tt> command.</p>
</div>
<div class="section" id="distributed-development-with-one-primary-developer">
<h2><a class="toc-backref" href="#id56">Distributed development with one primary developer</a></h2>
<p id="darcs-development-practices">This is how darcs itself is developed. There are many contributors to
darcs, but every contribution is reviewed and manually applied by myself.
For this sort of a situation, <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">send</span></tt> is ideal, since the barrier for
contributions is very low, which helps encourage contributors.</p>
<p>One could simply set the <tt class="docutils literal"><span class="pre">_darcs/prefs/email</span></tt> value to the project
mailing list, but I also use darcs send to send my changes to the main
server, so instead the email address is set to
"<tt class="docutils literal"><span class="pre">Davids</span> <span class="pre">Darcs</span> <span class="pre">Repo</span> <span class="pre"><droundy@abridgegame.org></span></tt>". My
<tt class="docutils literal"><span class="pre">.procmailrc</span></tt>
file on the server has the following rule:</p>
<pre class="literal-block">
:0
* ^TODavids Darcs Repo
|(umask 022; darcs apply --reply darcs-devel@abridgegame.org \
--repodir /path/to/repo --verify /path/to/allowed_keys)
</pre>
<p>This causes darcs apply to be run on any email sent to "Davids Darcs
Repo".
<tt class="docutils literal"><span class="pre">apply</span></tt> actually applies them only if they are signed by an
authorized key. Currently, the only authorized key is mine, but of course
this could be extended easily enough.</p>
<p>The central darcs repository contains the following values in its
<tt class="docutils literal"><span class="pre">_darcs/prefs/defaults</span></tt>:</p>
<pre class="literal-block">
apply test
apply verbose
apply happy-forwarding
</pre>
<p>The first line tells apply to always run the test suite. The test suite is
in fact the main reason I use send rather than push, since it allows me to
easily continue working (or put my computer to sleep) while the tests are
being run on the main server. The second line is just there to improve the
email response that I get when a patch has either been applied or failed
the tests. The third line makes darcs not complain about unsigned patches,
but just to forward them to <tt class="docutils literal"><span class="pre">darcs-devel</span></tt>.</p>
<p>On my development computer, I have in my <tt class="docutils literal"><span class="pre">.muttrc</span></tt> the following
alias, which allows me to easily apply patches that I get via email
directly to my darcs working directory:</p>
<pre class="literal-block">
macro pager A "<pipe-entry>(umask 022; darcs apply --no-test -v \
--repodir ~/darcs)"
</pre>
</div>
<div class="section" id="development-by-a-small-group-of-developers-in-one-office">
<h2><a class="toc-backref" href="#id57">Development by a small group of developers in one office</a></h2>
<p id="dft-development-practices">This section describes the development method used for the density
functional theory code DFT++, which is available at
<tt class="docutils literal"><span class="pre">http://dft.physics.cornell.edu/dft</span></tt>.</p>
<p>We have a number of workstations which all mount the same <tt class="docutils literal"><span class="pre">/home</span></tt> via NFS.
We created a special "dft" user, with the central repository living in that
user's home directory. The ssh public keys of authorized persons are added to
the "dft" user's <tt class="docutils literal"><span class="pre">.ssh/allowed_keys</span></tt>, and we commit patches to this
repository using
<tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">push</span></tt>. As in Section <a class="reference internal" href="#darcs-development-practices">darcs-development-practices</a>,
we have the central repository set to run the test suite before the push goes
through.</p>
<p>Note that no one ever runs as the dft user.</p>
<p>A subtlety that we ran into showed up in the running of the test suite.
Since our test suite includes the running of MPI programs, it must be run
in a directory that is mounted across our cluster. To achieve this, we set
the <tt class="docutils literal"><span class="pre">$DARCS_TMPDIR</span></tt> % following is added to make emacs color right:$
environment variable to <tt class="docutils literal"><span class="pre">~/tmp</span></tt>.</p>
<p>Note that even though there are only four active developers at the moment,
the distributed nature of darcs still plays a large role. Each developer
works on a feature until it is stable, a process that often takes quite a
few patches, and only once it is stable does he
<tt class="docutils literal"><span class="pre">push</span></tt> to the central repository.</p>
</div>
<div class="section" id="personal-development">
<h2><a class="toc-backref" href="#id58">Personal development</a></h2>
<p>It's easy to have several personal development trees using darcs, even
when working on a team or with shared code. The number and method of
using each personal tree is limited only by such grand limitations as:
your disk space, your imagination, available time, etc.</p>
<p>For example, if the central darcs repository for your development team
is $R_{c}$, you can create a local working directory for feature
$f_1$. This local working directory contains a full copy of $R_c$
(as of the time of the "darcs get" operation) and can be denoted
$R_1$. In the midst of working on feature $f_1$, you realize it
requires the development of a separate feature $f_2$. Rather than
intermingling $f_1$ and $f_2$ in the same working tree, you can create
a new working tree for working on $f_2$, where that working tree
contains the repository $R_2$.</p>
<p>While working on $f_2$, other developers may have made other changes;
these changes can be retrieved on a per-patch selection basis by
periodic "darcs pull" operations.</p>
<p>When your work on $f_2$ is completed, you can publish it for the use
of other developers by a "darcs push" (or "darcs send") from $R_2$
to $R_c$. Independently of the publishing of $f_2$, you can merge
your $f_2$ work into your $f_1$ working tree by a "darcs pull $R_2$"
in the $R_1$ development tree (or "darcs push" from $R_2$ to $R_1$).</p>
<p>When your work on $f_1$ is completed, you publish it as well by a
"darcs push" from $R_1$ to $R_c$.</p>
<p>Your local feature development efforts for $f_1$ or $f_2$ can each
consist of multiple patches. When pushing or pulling to other trees,
these patches can either all be selected or specific patches can be
selected. Thus, if you introduce a set of debugging calls into the
code, you can commit the debugging code in a distictly separate patch
(or patches) that you will not push to $R_c$.</p>
<div class="section" id="private-patches">
<h3>Private patches</h3>
<p>As discussed in the section above, a developer may have various
changes to their local development repositories that they do not ever
wish to publish to a group repository (e.g. personal debugging code),
but which they would like to keep in their local repository, and
perhaps even share amongst their local repositories.</p>
<p>This is easily done via darcs, since those private changes can be
committed in patches that are separate from other patches; during the
process of pushing patches to the common repository ($R_c$), the
developer is queried for which patches should be moved to ($R_c$) on a
patch-by-patch basis.</p>
<p>The <tt class="docutils literal"><span class="pre">--complement</span></tt> flag for the "darcs pull" operation can
further simplify this effort. If the developer copies (via "darcs
push" or "darcs pull") all private patches into a special
repository/working tree ($R_p$), then those patches are easily
disregarded for pulling by adding <tt class="docutils literal"><span class="pre">--complement</span></tt> to the "darcs
pull" line and listing $R_p$ after the primary source repository.</p>
<p>The <tt class="docutils literal"><span class="pre">--complement</span></tt> flag is only available for "darcs pull", and
not "darcs push" or "darcs send", requiring the user to have pull
access to the target repository. While the actual public repository
is often not shared in this manner, it's simple to create a local
version of the public repository to act as the staging area for that
public repository.</p>
<p>The following example extends the two feature addition example in the
previous section using a local staging repository ($R_l$) and a
private patch repository:</p>
<pre class="literal-block">
$ cd working-dir
$ darcs get http://server/repos/Rc Rl
$ darcs get Rl R1
$ cd R1
...development of f1
$ darcs record -m'p1: f1 initial work'
...
$ darcs record -m'p2: my debugging tracepoints'
...
$ cd ..
$ darcs get http://server/repos/Rc R2
$ cd R2
$ darcs pull -p p2 ../R1
... development of f2
$ darcs record -m'p3: f2 finished'
$ cd ..
$ darcs get Rl Rp
$ cd Rp
$ darcs pull -p p2 ../R2
$ cd ../Rl
$ darcs pull --complement ../R2 ../Rp
$ darcs send
... for publishing f2 patches to Rc
$ cd ../R1
$ darcs pull ../R2
... updates R1 with f2 changes from R2
... more development of f1
$ darcs record -m'p4: f1 feature finished.'
$ cd ../Rl
$ darcs pull --complement ../R1 ../Rp
$ darcs send
</pre>
<p>% Give some user-focused documentation on the formats introduced by Darcs 2</p>
</div>
</div>
</div>
<div class="section" id="repository-formats">
<h1><a class="toc-backref" href="#id59">Repository formats</a></h1>
<div class="section" id="id19">
<h2><a class="toc-backref" href="#id60">Introduction</a></h2>
<p>Darcs 2 introduces a couple of new repository formats and this chapter
is intended to serve as brief introduction to them and as an overview of
inter-operation between them.</p>
</div>
<div class="section" id="darcs-1-format">
<h2><a class="toc-backref" href="#id61">Darcs 1 format</a></h2>
<p>Darcs 1 format is the only format supported by 1.0.x versions of darcs.
Darcs 2 is capable of entirely interacting with darcs 1 format and still
defaults to darcs 1 format, but to take full advantage of new
capabilities of darcs 2 it be will necessary to upgrade to the newer
formats.</p>
</div>
<div class="section" id="hashed-format">
<h2><a class="toc-backref" href="#id62">Hashed format</a></h2>
<p>Hashed repository format is an intermediate format that interoperates
well with darcs 1 repositories. Darcs 2 can push/pull between darcs 1
format and hashed format repositories and can easily convert from one to
the other. Among its benefits, one of the most user obvious changes is
that the hashed format provides a more robust pristine format, that is
less susceptible to corruption from IDEs and automated tools.</p>
<p>Hashed format is recommend for all repositories used with darcs 2 that
need to interoperate with darcs 1 branches or darcs 1 developers. To
get the most out of hashed format usage it is recommended to enable a
global cache.</p>
<p>To convert an existing darcs 1 repository to hashed format simply
<tt class="docutils literal"><span class="pre">get</span></tt> a new copy with the hashed flag:</p>
<pre class="literal-block">
$ darcs get --hashed old-repo new-repo
</pre>
</div>
<div class="section" id="darcs-2-format">
<h2><a class="toc-backref" href="#id63">Darcs 2 format</a></h2>
<p>Darcs 2 format is the successor to darcs 1 format. It makes use of the
various improvements of the hashed repository format, with additional
benefits including an increased efficiency and robustness when dealing
with conflicting patches.</p>
<p>Darcs 2 format is recommended for projects that do not need to
interoperate with darcs 1 repositories or developers with versions of
darcs less than 2.0.0 installed. To get the most out of darcs 2 format
usage it is recommended to enable a global cache.</p>
<p>Initialize a new repository in darcs 2 format:</p>
<pre class="literal-block">
$ darcs init --darcs-2
</pre>
<p>Projects in darcs 1 format ready to move all development to darcs 2 can
convert an existing repository to darcs 2 format. This should be done
only once per family tree of related repositories, as converting each
branch separately may result in inter-repository corruption that can
lead to subtle and hard to diagnose problems when attempting to exchange
patches between seperately converted repositories. The recommendation
is to convert the branch of a project with the largest superset of
patches in the project and then recreate the branches from this superset
repository via <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt>, particularly with the usage of its
selection flags such as <tt class="docutils literal"><span class="pre">--context</span></tt>, <tt class="docutils literal"><span class="pre">--tag</span></tt> and
<tt class="docutils literal"><span class="pre">--to-match</span></tt>, and <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">obliterate</span></tt>, which can be used to
interactively remove patches that are not intended in the recreated
branch.</p>
<p>The command for conversion:</p>
<pre class="literal-block">
$ darcs convert d1repo d2repo
</pre>
</div>
</div>
<div class="section" id="darcs-commands">
<h1><a class="toc-backref" href="#id64">Darcs commands</a></h1>
<p>input{Darcs/Commands.lhs}</p>
<div class="section" id="options-apart-from-darcs-commands">
<h2><a class="toc-backref" href="#id65">Options apart from darcs commands</a></h2>
<p>begin{options}
--help, --overview
end{options}
Calling darcs with just <tt class="docutils literal"><span class="pre">--help</span></tt> as an argument gives a brief
summary of what commands are available.
The <tt class="docutils literal"><span class="pre">--overview</span></tt> option gives a more technical summary of
what the commands actually <em>do</em>.
begin{options}
--version, --exact-version
end{options}
Calling darcs with the flag <tt class="docutils literal"><span class="pre">--version</span></tt> tells you the version of
darcs you are using. Calling darcs with the flag <tt class="docutils literal"><span class="pre">--exact-version</span></tt>
gives the precise version of darcs, even if that version doesn't correspond
to a released version number. This is helpful with bug reports, especially
when running with a "latest" version of darcs.
begin{options}
--commands
end{options}
Similarly calling darcs with only <tt class="docutils literal"><span class="pre">--commands</span></tt> gives a simple list
of available commands. This latter arrangement is primarily intended for
the use of command-line autocompletion facilities, as are available in
bash.</p>
</div>
<div class="section" id="getting-help">
<h2><a class="toc-backref" href="#id66">Getting help</a></h2>
<p>input{Darcs/Commands/Help.lhs}</p>
</div>
<div class="section" id="creating-repositories">
<h2><a class="toc-backref" href="#id67">Creating repositories</a></h2>
<p>input{Darcs/Commands/Init.lhs}</p>
<p>input{Darcs/Commands/Get.lhs}</p>
<p>input{Darcs/Commands/Put.lhs}</p>
</div>
<div class="section" id="modifying-the-contents-of-a-repository">
<h2><a class="toc-backref" href="#id68">Modifying the contents of a repository</a></h2>
<p>input{Darcs/Commands/Add.lhs}</p>
<p>input{Darcs/Commands/Remove.lhs}</p>
<p>input{Darcs/Commands/Mv.lhs}</p>
<p>input{Darcs/Commands/Replace.lhs}</p>
</div>
<div class="section" id="working-with-changes">
<h2><a class="toc-backref" href="#id69">Working with changes</a></h2>
<p>input{Darcs/Commands/Record.lhs}</p>
<p>input{Darcs/Commands/Pull.lhs}</p>
<p>input{Darcs/Commands/Push.lhs}</p>
<p>input{Darcs/Commands/Send.lhs}</p>
<p>input{Darcs/Commands/Apply.lhs}</p>
</div>
<div class="section" id="seeing-what-you-ve-done">
<h2><a class="toc-backref" href="#id70">Seeing what you've done</a></h2>
<p>input{Darcs/Commands/WhatsNew.lhs}</p>
<p>input{Darcs/Commands/Changes.lhs}</p>
<p>input{Darcs/Commands/Show.lhs}</p>
</div>
<div class="section" id="more-advanced-commands">
<h2><a class="toc-backref" href="#id71">More advanced commands</a></h2>
<p>input{Darcs/Commands/Tag.lhs}</p>
<p>input{Darcs/Commands/SetPref.lhs}</p>
<p>input{Darcs/Commands/Check.lhs}</p>
<p>input{Darcs/Commands/Optimize.lhs}</p>
</div>
<div class="section" id="undoing-redoing-and-running-in-circles">
<h2><a class="toc-backref" href="#id72">Undoing, redoing and running in circles</a></h2>
<p>input{Darcs/Commands/AmendRecord.lhs}</p>
<p>input{Darcs/Commands/Rollback.lhs}</p>
<p>input{Darcs/Commands/Unrecord.lhs}</p>
<p>input{Darcs/Commands/Revert.lhs}</p>
<p>input{Darcs/Commands/Unrevert.lhs}</p>
</div>
<div class="section" id="advanced-examination-of-the-repository">
<h2><a class="toc-backref" href="#id73">Advanced examination of the repository</a></h2>
<p>input{Darcs/Commands/Diff.lhs}</p>
<p>input{Darcs/Commands/Annotate.lhs}</p>
<p>% Includes the show commands.
input{Darcs/Commands/Show.lhs}</p>
</div>
<div class="section" id="rarely-needed-and-obscure-commands">
<h2><a class="toc-backref" href="#id74">Rarely needed and obscure commands</a></h2>
<p>input{Darcs/Commands/Convert.lhs}</p>
<p>input{Darcs/Commands/MarkConflicts.lhs}</p>
<p>input{Darcs/Commands/Dist.lhs}</p>
<p>input{Darcs/Commands/TrackDown.lhs}</p>
<p>input{Darcs/Commands/Repair.lhs}</p>
<p>appendix</p>
<p>input{Darcs/Patch.lhs}</p>
<p>input{Darcs/Repository/DarcsRepo.lhs}</p>
</div>
</div>
<div class="system-messages section">
<h1>Docutils System Messages</h1>
<div class="system-message" id="id75">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 63); <em><a href="#id76">backlink</a></em></p>
Unknown target name: "patch".</div>
<div class="system-message" id="id77">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 140); <em><a href="#id78">backlink</a></em></p>
Unknown target name: "token_replace".</div>
<div class="system-message" id="id79">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 162); <em><a href="#id80">backlink</a></em></p>
Unknown target name: "patch".</div>
<div class="system-message" id="id81">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 162); <em><a href="#id82">backlink</a></em></p>
Unknown target name: "merge_thm".</div>
<div class="system-message" id="id83">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 668); <em><a href="#id84">backlink</a></em></p>
Unknown target name: "whatsnew".</div>
<div class="system-message" id="id85">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">darcs.txt</tt>, line 1157); <em><a href="#id86">backlink</a></em></p>
Unknown target name: "darcs_email".</div>
<div class="system-message" id="id87">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">best_practices.txt</tt>, line 1772); <em><a href="#id88">backlink</a></em></p>
Unknown target name: "initialize".</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Page ###Page###
</div>
</body>
</html>