Show darcs-manual.html syntax highlighted
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Darcs 1.0.6pre1 (unknown)
Darcs
</TITLE>
<META NAME="description" CONTENT="Darcs 1.0.6pre1 (unknown)
Darcs
">
<META NAME="keywords" CONTENT="bigpage">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="bigpage.css">
</HEAD>
<BODY >
<DIV CLASS="navigation"><!--Navigation Panel-->
<IMG WIDTH="22" HEIGHT="22" title="Next" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
SRC="./nx_grp_g.png">
<IMG WIDTH="22" HEIGHT="22" title="Up" ALIGN="BOTTOM" BORDER="0" ALT="up"
SRC="./up_g.png">
<IMG WIDTH="22" HEIGHT="22" title="Previous" ALIGN="BOTTOM" BORDER="0" ALT="previous"
SRC="./prev_g.png">
<BR>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<P>
<P>
<H1 ALIGN="CENTER">
Darcs 1.0.6pre1 (unknown)
<BR><BIG CLASS="XLARGE"><I>Darcs</I></BIG>
</H1>
<DIV CLASS="author_info">
<P ALIGN="CENTER"><STRONG>David Roundy
</STRONG></P>
</DIV>
<P>
<BR>
<H2><A NAME="SECTION00100000000000000000">
Contents</A>
</H2>
<!--Table of Contents-->
<UL CLASS="TofC">
<LI><A NAME="tex2html139"
HREF="bigpage.html#SECTION00200000000000000000">Introduction</A>
<UL>
<LI><A NAME="tex2html140"
HREF="bigpage.html#SECTION00210000000000000000">Features</A>
<LI><A NAME="tex2html141"
HREF="bigpage.html#SECTION00220000000000000000">Switching from CVS</A>
<LI><A NAME="tex2html142"
HREF="bigpage.html#SECTION00230000000000000000">Switching from arch</A>
</UL>
<BR>
<LI><A NAME="tex2html143"
HREF="bigpage.html#SECTION00300000000000000000">Building darcs</A>
<UL>
<LI><A NAME="tex2html144"
HREF="bigpage.html#SECTION00310000000000000000">Prerequisites</A>
<LI><A NAME="tex2html145"
HREF="bigpage.html#SECTION00320000000000000000">Building on Mac OS X</A>
<LI><A NAME="tex2html146"
HREF="bigpage.html#SECTION00330000000000000000">Building on Microsoft Windows</A>
<LI><A NAME="tex2html147"
HREF="bigpage.html#SECTION00340000000000000000">Building from tarball</A>
<LI><A NAME="tex2html148"
HREF="bigpage.html#SECTION00350000000000000000">Building darcs from the repository</A>
<LI><A NAME="tex2html149"
HREF="bigpage.html#SECTION00360000000000000000">Building darcs with git</A>
<LI><A NAME="tex2html150"
HREF="bigpage.html#SECTION00370000000000000000">Submitting patches to darcs</A>
</UL>
<BR>
<LI><A NAME="tex2html151"
HREF="bigpage.html#SECTION00400000000000000000">Getting started</A>
<UL>
<LI><A NAME="tex2html152"
HREF="bigpage.html#SECTION00410000000000000000">Creating your repository</A>
<LI><A NAME="tex2html153"
HREF="bigpage.html#SECTION00420000000000000000">Making changes</A>
<LI><A NAME="tex2html154"
HREF="bigpage.html#SECTION00430000000000000000">Making your repository visible to others</A>
<LI><A NAME="tex2html155"
HREF="bigpage.html#SECTION00440000000000000000">Getting changes made to another repository</A>
<LI><A NAME="tex2html156"
HREF="bigpage.html#SECTION00450000000000000000">Moving patches from one repo to another</A>
<UL>
<LI><A NAME="tex2html157"
HREF="bigpage.html#SECTION00451000000000000000">All pulls</A>
<LI><A NAME="tex2html158"
HREF="bigpage.html#SECTION00452000000000000000">Send and apply manually</A>
<LI><A NAME="tex2html159"
HREF="bigpage.html#SECTION00453000000000000000">Push</A>
<LI><A NAME="tex2html160"
HREF="bigpage.html#SECTION00454000000000000000">Push --apply-as</A>
<LI><A NAME="tex2html161"
HREF="bigpage.html#SECTION00455000000000000000">Sending signed patches by email</A>
</UL>
<LI><A NAME="tex2html162"
HREF="bigpage.html#SECTION00460000000000000000">Reducing disk space usage</A>
<UL>
<LI><A NAME="tex2html163"
HREF="bigpage.html#SECTION00461000000000000000">Linking between repositories</A>
<LI><A NAME="tex2html164"
HREF="bigpage.html#SECTION00462000000000000000">Alternate formats for the pristine tree</A>
</UL>
</UL>
<BR>
<LI><A NAME="tex2html165"
HREF="bigpage.html#SECTION00500000000000000000">Configuring darcs</A>
<UL>
<LI><A NAME="tex2html166"
HREF="bigpage.html#SECTION00510000000000000000">prefs</A>
<LI><A NAME="tex2html167"
HREF="bigpage.html#SECTION00520000000000000000">Environment variables</A>
<LI><A NAME="tex2html168"
HREF="bigpage.html#SECTION00530000000000000000">Highlighted output</A>
<LI><A NAME="tex2html169"
HREF="bigpage.html#SECTION00540000000000000000">Character escaping and non-ASCII character encodings</A>
</UL>
<BR>
<LI><A NAME="tex2html170"
HREF="bigpage.html#SECTION00600000000000000000">Best practices</A>
<UL>
<LI><A NAME="tex2html171"
HREF="bigpage.html#SECTION00610000000000000000">Introduction</A>
<LI><A NAME="tex2html172"
HREF="bigpage.html#SECTION00620000000000000000">Creating patches</A>
<UL>
<LI><A NAME="tex2html173"
HREF="bigpage.html#SECTION00621000000000000000">Changes</A>
<LI><A NAME="tex2html174"
HREF="bigpage.html#SECTION00622000000000000000">Keeping or discarding changes</A>
<LI><A NAME="tex2html175"
HREF="bigpage.html#SECTION00623000000000000000">Unrecording changes</A>
<LI><A NAME="tex2html176"
HREF="bigpage.html#SECTION00624000000000000000">Special patches and pending</A>
</UL>
<LI><A NAME="tex2html177"
HREF="bigpage.html#SECTION00630000000000000000">Using patches</A>
<UL>
<LI><A NAME="tex2html178"
HREF="bigpage.html#SECTION00631000000000000000">Dependencies</A>
<LI><A NAME="tex2html179"
HREF="bigpage.html#SECTION00632000000000000000">Branches: just normal repositories</A>
<LI><A NAME="tex2html180"
HREF="bigpage.html#SECTION00633000000000000000">Moving patches around--no versions</A>
<LI><A NAME="tex2html181"
HREF="bigpage.html#SECTION00634000000000000000">Tags--versions</A>
<LI><A NAME="tex2html182"
HREF="bigpage.html#SECTION00635000000000000000">Conflicts</A>
<LI><A NAME="tex2html183"
HREF="bigpage.html#SECTION00636000000000000000">Resolving conflicts</A>
</UL>
<LI><A NAME="tex2html184"
HREF="bigpage.html#SECTION00640000000000000000">Distributed development with one primary developer</A>
<LI><A NAME="tex2html185"
HREF="bigpage.html#SECTION00650000000000000000">Development by a small group of developers in one office</A>
</UL>
<BR>
<LI><A NAME="tex2html186"
HREF="bigpage.html#SECTION00700000000000000000">Darcs commands</A>
<UL>
<LI><A NAME="tex2html187"
HREF="bigpage.html#SECTION00710000000000000000">Common options to darcs commands</A>
<LI><A NAME="tex2html188"
HREF="bigpage.html#SECTION00720000000000000000">Options apart from darcs commands</A>
<LI><A NAME="tex2html189"
HREF="bigpage.html#SECTION00730000000000000000">Creating repositories</A>
<UL>
<LI><A NAME="tex2html190"
HREF="bigpage.html#SECTION00731000000000000000">darcs initialize</A>
<LI><A NAME="tex2html191"
HREF="bigpage.html#SECTION00732000000000000000">darcs get</A>
<LI><A NAME="tex2html192"
HREF="bigpage.html#SECTION00733000000000000000">darcs put</A>
</UL>
<LI><A NAME="tex2html193"
HREF="bigpage.html#SECTION00740000000000000000">Modifying the contents of a repo</A>
<UL>
<LI><A NAME="tex2html194"
HREF="bigpage.html#SECTION00741000000000000000">darcs add</A>
<LI><A NAME="tex2html195"
HREF="bigpage.html#SECTION00742000000000000000">darcs remove</A>
<LI><A NAME="tex2html196"
HREF="bigpage.html#SECTION00743000000000000000">darcs mv</A>
<LI><A NAME="tex2html197"
HREF="bigpage.html#SECTION00744000000000000000">darcs replace</A>
</UL>
<LI><A NAME="tex2html198"
HREF="bigpage.html#SECTION00750000000000000000">Working with changes</A>
<UL>
<LI><A NAME="tex2html199"
HREF="bigpage.html#SECTION00751000000000000000">darcs record</A>
<LI><A NAME="tex2html200"
HREF="bigpage.html#SECTION00752000000000000000">darcs pull</A>
<LI><A NAME="tex2html201"
HREF="bigpage.html#SECTION00753000000000000000">darcs push</A>
<LI><A NAME="tex2html202"
HREF="bigpage.html#SECTION00754000000000000000">darcs send</A>
<LI><A NAME="tex2html203"
HREF="bigpage.html#SECTION00755000000000000000">darcs apply</A>
</UL>
<LI><A NAME="tex2html204"
HREF="bigpage.html#SECTION00760000000000000000">Seeing what you've done</A>
<UL>
<LI><A NAME="tex2html205"
HREF="bigpage.html#SECTION00761000000000000000">darcs whatsnew</A>
<LI><A NAME="tex2html206"
HREF="bigpage.html#SECTION00762000000000000000">darcs changes</A>
<LI><A NAME="tex2html207"
HREF="bigpage.html#SECTION00763000000000000000">darcs query manifest</A>
</UL>
<LI><A NAME="tex2html208"
HREF="bigpage.html#SECTION00770000000000000000">More advanced commands</A>
<UL>
<LI><A NAME="tex2html209"
HREF="bigpage.html#SECTION00771000000000000000">darcs tag</A>
<LI><A NAME="tex2html210"
HREF="bigpage.html#SECTION00772000000000000000">darcs setpref</A>
<LI><A NAME="tex2html211"
HREF="bigpage.html#SECTION00773000000000000000">darcs check</A>
<LI><A NAME="tex2html212"
HREF="bigpage.html#SECTION00774000000000000000">darcs optimize</A>
</UL>
<LI><A NAME="tex2html213"
HREF="bigpage.html#SECTION00780000000000000000">Undoing, redoing and running in circles</A>
<UL>
<LI><A NAME="tex2html214"
HREF="bigpage.html#SECTION00781000000000000000">darcs amend-record</A>
<LI><A NAME="tex2html215"
HREF="bigpage.html#SECTION00782000000000000000">darcs rollback</A>
<LI><A NAME="tex2html216"
HREF="bigpage.html#SECTION00783000000000000000">darcs unrecord</A>
<LI><A NAME="tex2html217"
HREF="bigpage.html#SECTION00784000000000000000">darcs unpull</A>
<LI><A NAME="tex2html218"
HREF="bigpage.html#SECTION00785000000000000000">darcs obliterate</A>
<LI><A NAME="tex2html219"
HREF="bigpage.html#SECTION00786000000000000000">darcs revert</A>
<LI><A NAME="tex2html220"
HREF="bigpage.html#SECTION00787000000000000000">darcs unrevert</A>
</UL>
<LI><A NAME="tex2html221"
HREF="bigpage.html#SECTION00790000000000000000">Advanced examination of the repository</A>
<UL>
<LI><A NAME="tex2html222"
HREF="bigpage.html#SECTION00791000000000000000">darcs diff</A>
<LI><A NAME="tex2html223"
HREF="bigpage.html#SECTION00792000000000000000">darcs annotate</A>
<LI><A NAME="tex2html224"
HREF="bigpage.html#SECTION00793000000000000000">darcs query manifest</A>
</UL>
<LI><A NAME="tex2html225"
HREF="bigpage.html#SECTION007100000000000000000">Rarely needed and obscure commands</A>
<UL>
<LI><A NAME="tex2html226"
HREF="bigpage.html#SECTION007101000000000000000">darcs resolve</A>
<LI><A NAME="tex2html227"
HREF="bigpage.html#SECTION007102000000000000000">darcs dist</A>
<LI><A NAME="tex2html228"
HREF="bigpage.html#SECTION007103000000000000000">darcs trackdown</A>
<LI><A NAME="tex2html229"
HREF="bigpage.html#SECTION007104000000000000000">darcs repair</A>
</UL>
</UL>
<BR>
<LI><A NAME="tex2html230"
HREF="bigpage.html#SECTION00800000000000000000">Theory of patches</A>
<UL>
<LI><A NAME="tex2html231"
HREF="bigpage.html#SECTION00810000000000000000">Background</A>
<LI><A NAME="tex2html232"
HREF="bigpage.html#SECTION00820000000000000000">Introduction</A>
<LI><A NAME="tex2html233"
HREF="bigpage.html#SECTION00830000000000000000">Applying patches</A>
<UL>
<LI><A NAME="tex2html234"
HREF="bigpage.html#SECTION00831000000000000000">Hunk patches</A>
<LI><A NAME="tex2html235"
HREF="bigpage.html#SECTION00832000000000000000">Token replace patches</A>
</UL>
<LI><A NAME="tex2html236"
HREF="bigpage.html#SECTION00840000000000000000">Patch relationships</A>
<LI><A NAME="tex2html237"
HREF="bigpage.html#SECTION00850000000000000000">Commuting patches</A>
<UL>
<LI><A NAME="tex2html238"
HREF="bigpage.html#SECTION00851000000000000000">Composite patches</A>
<LI><A NAME="tex2html239"
HREF="bigpage.html#SECTION00852000000000000000">How merges are actually performed</A>
<LI><A NAME="tex2html240"
HREF="bigpage.html#SECTION00853000000000000000">File patches</A>
<LI><A NAME="tex2html241"
HREF="bigpage.html#SECTION00854000000000000000">Hunks</A>
</UL>
<LI><A NAME="tex2html242"
HREF="bigpage.html#SECTION00860000000000000000">Conflicts</A>
<LI><A NAME="tex2html243"
HREF="bigpage.html#SECTION00870000000000000000">Patch string formatting</A>
</UL>
<BR>
<LI><A NAME="tex2html244"
HREF="bigpage.html#SECTION00900000000000000000">DarcsRepo format</A>
<LI><A NAME="tex2html245"
HREF="bigpage.html#SECTION001000000000000000000">The GNU General Public License</A>
<UL>
<LI><A NAME="tex2html246"
HREF="bigpage.html#SECTION001030000000000000000">Appendix: How to Apply These Terms to Your New Programs</A>
</UL></UL>
<!--End of Table of Contents-->
<P>
<H1><A NAME="SECTION00200000000000000000">
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>
<H4><A NAME="SECTION00200010000000000000">
Every source tree a branch</A>
</H4>
The primary simplifying notion of darcs is that <SPAN CLASS="textit">every</SPAN> 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.
<P>
<H4><A NAME="SECTION00200020000000000000">
Theory of patches</A>
</H4>
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="#Patch"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></A>.
<P>
<H4><A NAME="SECTION00200030000000000000">
A simple advanced tool</A>
</H4>
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.
<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 <code>ssh</code> 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 HREF="#configuring"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></A>
for details.
<P>
The recommended method is to send patches through gpg-signed email
messages, which has the advantage of being mostly asynchronous.
<P>
<H4><A NAME="SECTION00200040000000000000">
Keeping track of changes rather than versions</A>
</H4>
<P>
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).
<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>
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>
In the world of darcs, the source tree is <SPAN CLASS="textit">not</SPAN> 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>
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 <SPAN CLASS="textit">creating</SPAN> 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="#token_replace"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></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>
The patch formalism discussed in Appendix <A HREF="#Patch"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></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="#merge_thm"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></A>, which is used extensively in the manipulation of
merges.
<P>
<H1><A NAME="SECTION00210000000000000000">
Features</A>
</H1>
<P>
<H4><A NAME="SECTION00210010000000000000">
Record changes locally</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210020000000000000">
Interactive records</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210030000000000000">
Unrecord local changes</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210040000000000000">
Interactive everything else</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210050000000000000">
Test suites</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210060000000000000">
Any old server</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210070000000000000">
You decide write permissions</A>
</H4>
Darcs doesn't try to manage write access. That's your business. Supported
push methods include direct ssh access (if you're willing to <SPAN CLASS="textit">give</SPAN>
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).
<P>
<H4><A NAME="SECTION00210080000000000000">
Symmetric repositories</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00210090000000000000">
CGI script</A>
</H4>
Darcs has a CGI script that allows browsing of the repositories.
<P>
<H4><A NAME="SECTION002100100000000000000">
Portable</A>
</H4>
Darcs runs on UNIX (or UNIX-like) systems (which includes Mac OS X) as well
as on Microsoft Windows.
<P>
<H4><A NAME="SECTION002100110000000000000">
File and directory moves</A>
</H4>
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.
<P>
<H4><A NAME="SECTION002100120000000000000">
Token replace</A>
</H4>
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.
<P>
<H4><A NAME="SECTION002100130000000000000">
Configurable defaults</A>
</H4>
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.
<P>
<H1><A NAME="SECTION00220000000000000000">
Switching from CVS</A>
</H1>
<P>
Darcs is refreshingly different from CVS.
<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>
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 <SPAN CLASS="textit">push</SPAN> 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>
<H4><A NAME="SECTION00220010000000000000">
Darcs commands for CVS users</A>
</H4>
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:
<BR><DL>
<DT><STRONG><TT>cvs checkout</TT> </STRONG></DT>
<DD><TT>darcs get</TT>
</DD>
<DT><STRONG><TT>cvs update</TT> </STRONG></DT>
<DD><TT>darcs pull</TT>
</DD>
<DT><STRONG><TT>cvs -n update</TT> </STRONG></DT>
<DD><TT>darcs pull <code>--dry-run</code></TT>
(summarize remote changes)
</DD>
<DT><STRONG><TT>cvs -n update</TT> </STRONG></DT>
<DD><TT>darcs whatsnew <code>--summary</code></TT>
(summarize local changes)
</DD>
<DT><STRONG><TT>cvs -n update | grep '?'</TT> </STRONG></DT>
<DD><TT>darcs whatsnew -ls | grep <code>^a</code> </TT>
(list potential files to add)
</DD>
<DT><STRONG><TT>rm foo.txt; cvs update foo.txt</TT> </STRONG></DT>
<DD><TT>darcs revert foo.txt</TT>
(revert to foo.txt from repo)
</DD>
<DT><STRONG><TT>cvs diff</TT> </STRONG></DT>
<DD><TT>darcs whatsnew</TT>
(if checking local changes)
</DD>
<DT><STRONG><TT>cvs diff</TT> </STRONG></DT>
<DD><TT>darcs diff</TT>
(if checking recorded changes)
</DD>
<DT><STRONG><TT>cvs commit</TT> </STRONG></DT>
<DD><TT>darcs record</TT>
(if committing locally)
</DD>
<DT><STRONG><TT>cvs commit</TT> </STRONG></DT>
<DD><TT>darcs tag</TT>
(if marking a version for later use)
</DD>
<DT><STRONG><TT>cvs commit</TT> </STRONG></DT>
<DD><TT>darcs push</TT> or <TT>darcs send</TT>
(if committing remotely)
</DD>
<DT><STRONG><TT>cvs diff | mail</TT> </STRONG></DT>
<DD><TT>darcs send</TT>
</DD>
<DT><STRONG><TT>cvs add</TT> </STRONG></DT>
<DD><TT>darcs add</TT>
</DD>
<DT><STRONG><TT>cvs tag -b</TT> </STRONG></DT>
<DD><TT>darcs get</TT>
</DD>
<DT><STRONG><TT>cvs tag</TT> </STRONG></DT>
<DD><TT>darcs tag</TT>
</DD>
</DL>
<P>
<H4><A NAME="SECTION00220020000000000000">
Migrating CVS repositories to darcs</A>
</H4>
<P>
Tools and instructions for migrating CVS repositories to darcs are provided
on the darcs community website:
<A NAME="tex2html1"
HREF="http://darcs.net/DarcsWiki/ConvertingFromCvs">http://darcs.net/DarcsWiki/ConvertingFromCvs</A>
<P>
<H1><A NAME="SECTION00230000000000000000">
Switching from arch</A>
</H1>
<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>
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 -- <code>tla</code> <code>get</code>,
<code>update</code>, <code>commit</code>, <code>archive-mirror</code> and so on.
<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:
<code>darcs</code> <code>record</code>, which stores edits into your local
repository, and <code>pull</code>, which moves data between repositories.
(<code>darcs</code> <code>push</code> is merely the opposite of <code>pull</code>;
<code>send</code> and <code>apply</code> are just the two halves of <code>push</code>).
<P>
<H4><A NAME="SECTION00230010000000000000">
Darcs commands for arch users</A>
</H4>
<P>
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:
<BR><DL>
<DT><STRONG><TT>tla init-tree</TT> </STRONG></DT>
<DD><TT>darcs initialize</TT>
</DD>
<DT><STRONG><TT>tla get</TT> </STRONG></DT>
<DD><TT>darcs get</TT>
</DD>
<DT><STRONG><TT>tla update</TT> </STRONG></DT>
<DD><TT>darcs pull</TT>
</DD>
<DT><STRONG><TT>tla file-diffs f | patch -R </TT> </STRONG></DT>
<DD><TT>darcs revert</TT>
</DD>
<DT><STRONG><TT>tla changes -diffs</TT> </STRONG></DT>
<DD><TT>darcs whatsnew</TT>
</DD>
<DT><STRONG><TT>tla logs</TT> </STRONG></DT>
<DD><TT>darcs changes</TT>
</DD>
<DT><STRONG><TT>tla file-diffs</TT> </STRONG></DT>
<DD><TT>darcs diff -u</TT>
</DD>
<DT><STRONG><TT>tla add</TT> </STRONG></DT>
<DD><TT>darcs add</TT>
</DD>
<DT><STRONG><TT>tla mv</TT> </STRONG></DT>
<DD><TT>darcs mv</TT>
(not <TT>tla move</TT>)
</DD>
<DT><STRONG><TT>tla commit</TT> </STRONG></DT>
<DD><TT>darcs record</TT>
(if committing locally)
</DD>
<DT><STRONG><TT>tla commit</TT> </STRONG></DT>
<DD><TT>darcs tag</TT>
(if marking a version for later use)
</DD>
<DT><STRONG><TT>tla commit</TT> </STRONG></DT>
<DD><TT>darcs push</TT> or <TT>darcs send</TT>
(if committing remotely)
</DD>
<DT><STRONG><TT>tla archive-mirror</TT> </STRONG></DT>
<DD><TT>darcs pull</TT> or <TT>darcs push</TT>
</DD>
<DT><STRONG><TT>tla tag</TT> </STRONG></DT>
<DD><TT>darcs get</TT>
(if creating a branch)
</DD>
<DT><STRONG><TT>tla tag</TT> </STRONG></DT>
<DD><TT>darcs tag</TT>
(if creating a tag).
</DD>
</DL>
<P>
<H4><A NAME="SECTION00230020000000000000">
Migrating arch repositories to darcs</A>
</H4>
<P>
Tools and instructions for migrating arch repositories to darcs are provided
on the darcs community website:
<A NAME="tex2html2"
HREF="http://darcs.net/DarcsWiki/ConvertingFromArch">http://darcs.net/DarcsWiki/ConvertingFromArch</A>
<P>
<H1><A NAME="SECTION00300000000000000000">
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>
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>
<H1><A NAME="SECTION00310000000000000000">
Prerequisites</A>
</H1>
To build darcs you will need to have <TT>ghc</TT>, the Glorious Glasgow
Haskell Compiler. You should have at the very minimum version 6.2.
<P>
It is a good idea (but not required) to have a recent version of libcurl
installed. If not, you will at least need to have either <TT>wget</TT> or
<TT>curl</TT> installed if you want to be able to grab repos remotely over
normal network protocols (ftp or http). You also might want to have scp
available if you want to grab your repos over ssh...
<P>
To send patches, you will also need to have a working
<code>/usr/sbin/sendmail</code> or <code>/usr/lib/sendmail</code>, which is provided
by most mail transport agents, and is generally available on linux and
BSD systems. It's also there on Mac OS X. However, if you don't have this,
it won't stop you from building darcs.
<P>
To use the <code>diff</code> command of darcs, a <code>diff</code> program supporting
options <code>-r</code> (recursive diff) and <code>-N</code> (show new files as
differences against an empty file) is required. The <code>configure</code>
script will look for <code>gdiff</code>, <code>gnudiff</code> and <code>diff</code> in this
order. You can force the use of another program by setting the <code>DIFF</code>
environment variable before running <code>configure</code>.
<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>
<H1><A NAME="SECTION00320000000000000000">
Building on Mac OS X</A>
</H1>
To build on Mac OS X, you will need the Apple Developer Tools and the ghc
6.4 package installed.
<P>
<H1><A NAME="SECTION00330000000000000000">
Building on Microsoft Windows</A>
</H1>
To build on Microsoft Windows, you will need:
<P>
<UL>
<LI><A NAME="tex2html3"
HREF="http://www.mingw.org/">MinGW</A>
which provides the GCC
toolchain for win32.
</LI>
<LI><A NAME="tex2html4"
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 NAME="tex2html5"
HREF="http://www.gzip.org/zlib/">zlib-1.2.1+</A>
library
and headers.
</LI>
<LI><A NAME="tex2html6"
HREF="http://curl.haxx.se/">curl-7.12.2+</A>
library
and headers.
</LI>
<LI>If building with an SSL enabled curl you will need the OpenSSL
libraries, unofficial builds are available at
<A NAME="tex2html7"
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 <code><ghc-dir>/gcc-lib/include</code> and libraries in
<code><ghc-dir>/gcc-lib</code>. MinGW stores headers in
<code><mingw-dir>/include</code> and libraries in <code><mingw-dir>/lib</code>.
<P>
Set PATH to include the <code><msys-dir>/bin</code>, <code><mingw-dir>/bin</code>,
<code><curl-dir></code>, and a directory containing a pre-built darcs.exe if you
want the build's patch context stored for `<code>darcs --exact-version</code>'.
<P>
<PRE>
C:\darcs> cd <darcs-source-dir>
C:\darcs> sh
$ export GHC=/c/<ghc-dir>/bin/ghc.exe
$ autoconf
$ ./configure --disable-mmap --target=mingw
$ make
</PRE>
<P>
<H1><A NAME="SECTION00340000000000000000">
Building from tarball</A>
</H1>
If you get darcs from a tarball, the procedure (after unpacking the tarball
itself) is as follows:
<PRE>
% ./configure
% make
# Optional, but recommended to test compatibility with your environment.
% make test
% make install
</PRE>
<P>
There are options to configure that you may want to check out with
<PRE>
% ./configure --help
</PRE>
<P>
If your header files are installed in a non-standard location, you may need
to define the <code>CFLAGS</code> and <code>CPPFLAGS</code> environment variables to
include the path to the headers. e.g. on NetBSD, you may need to run
<PRE>
% CFLAGS=-I/usr/pkg/include CPPFLAGS=-I/usr/pkg/include ./configure
</PRE>
<P>
<H1><A NAME="SECTION00350000000000000000">
Building darcs from the repository</A>
</H1>
To build the latest darcs from its repository, you will first need a
working copy of darcs. You can get darcs using:
<PRE>
% darcs get -v http://abridgegame.org/repos/darcs
</PRE>
and once you have the darcs repository you can bring it up to date with a
<PRE>
% 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
<code>autoconf</code> first.
<P>
You'll need <code>autoconf</code> 2.50 or higher. Some systems have more than one
version of <code>autoconf</code> installed. For example, <code>autoconf</code> may point to
version 2.13, while <code>autoconf259</code> runs version 2.59.
<P>
Also note that <code>make</code> is really "GNU make". On some systems, such as
the *BSDs, you may need to type <code>gmake</code> instead of make for this to work.
<P>
If you want to create readable documentation you'll need to have latex installed.
<PRE>
% autoconf
% ./configure
% make
% make install
</PRE>
<P>
If you want to tweak the configure options, you'll need to run <TT> ./configure</TT> yourself after the make, and then run make again.
<P>
<H1><A NAME="SECTION00360000000000000000">
Building darcs with git</A>
</H1>
<P>
To enable git support, you first need to grab a copy of the git
source code; since darcs doesn't yet have the capability of accessing
remote git repositories, you'll have to either download a tarball or use
git itself to clone a git repository. Compile git (no need to
install); this will create a file ``<code>libgit.a</code>''. Then create a
symlink to the git source directory named ``<code>git</code>'' in your darcs
source directory, configure darcs using the ``<code>--enable-git</code>''
option, and build darcs as usual.
<P>
<H1><A NAME="SECTION00370000000000000000">
Submitting patches to darcs</A>
</H1>
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 <code>building_darcs.tex</code>) based
on your experience building darcs...
<P>
To do so, just record your changes (which you made in the darcs repository)
<PRE>
% darcs record --no-test
</PRE>
making sure to give the patch a nice descriptive name. The
<code>--no-test</code> 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
<PRE>
% darcs send -u
</PRE>
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>
<H1><A NAME="SECTION00400000000000000000">
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>
<H1><A NAME="SECTION00410000000000000000">
Creating your repository</A>
</H1>
<P>
Creating your repository in the first place just involves telling darcs to
create the special directory (called <TT>_darcs</TT>) in your project tree,
which will hold the revision information. This is done by simply calling
from the root directory of your project:
<PRE>
% cd my_project/
% darcs initialize
</PRE>
This creates the <code>_darcs</code> 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 <code>darcs add</code><A NAME="tex2html8"
HREF="#foot199"><SUP><SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A>:
<PRE>
% darcs add *.c Makefile.am configure.ac
</PRE>
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.
<PRE>
% darcs record --all
What is the patch name? Initial revision.
</PRE>
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>
<H1><A NAME="SECTION00420000000000000000">
Making changes</A>
</H1>
<P>
Now that we have created our repository, make a change to one or more of
your files. After making the modification run:
<PRE>
% darcs whatsnew
</PRE>
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="#whatsnew"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></A>, which describes the whatsnew command in
detail.
<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>
To record a patch simply type:
<PRE>
% darcs record
</PRE>
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>
You can now rerun whatsnew, and see that indeed the changes you have
recorded are no longer marked as new.
<P>
<H1><A NAME="SECTION00430000000000000000">
Making your repository visible to others</A>
</H1>
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>/var/www/repos</TT>, and then put a symlink to your repo there:
<PRE>
% cd /var/www/repos
% ln -s /home/username/myproject .
</PRE>
<P>
As long as you're running a web server and making your repo 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 <code>make installserver</code>, which
installs the program <code>darcs_cgi</code> at <code>/usr/lib/cgi-bin/darcs</code>. You
also will need to create a cache directory named
<code>/var/cache/darcs_cgi</code>, 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 repos by pointing their web browsers at
<code>http://your.server.org/cgi-bin/darcs</code>.
<P>
<H1><A NAME="SECTION00440000000000000000">
Getting changes made to another repository</A>
</H1>
Ok, so I can now browse your repository using my web browser... so
what? How do I get your changes into <SPAN CLASS="textit">my</SPAN> repository, where they can
do some good? It couldn't be easier. I just <code>cd</code> into my repository,
and there type:
<PRE>
% darcs pull http://your.server.org/repos/yourproject
</PRE>
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>
Of course, maybe I don't even have a copy of your repository. In that case
I'd want to do a
<PRE>
% darcs get http://your.server.org/repos/yourproject
</PRE>
which gets the whole repo.
<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>
Get, pull and push also work over ssh. Ssh-paths are of the same form
accepted by scp, namely <code>[username@]host:/path/to/repository</code>.
<P>
<H1><A NAME="SECTION00450000000000000000">
Moving patches from one repo to another</A>
</H1>
<P>
Darcs is flexible as to how you move patches from one repo 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>
<H2><A NAME="SECTION00451000000000000000">
All pulls</A>
</H2>
<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 <code>darcs pull</code> in the repo 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>
<H2><A NAME="SECTION00452000000000000000">
Send and apply manually</A>
</H2>
<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 darcs
send 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 repo) run darcs apply to apply the patches contained
in the bundle. This is also quite a simple method since, like the all-pull
method, it doesn't require that you give anyone write access to your
repository. But it's less convenient, since you have to keep track of the
patch bundle (in the email, or whatever).
<P>
If you use the send and apply method with email, you'll probably want to
create a <code>_darcs/prefs/email</code> file containing your email address.
This way anyone who sends to your repository will automatically send the
patch bundle to your email address.
<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 <code>.muttrc</code>
the following
<PRE>
macro pager A "<pipe-entry>darcs apply --verbose --mark-conflicts \
--reply droundy@abridgegame.org --repodir ~/darcs"
</PRE>
which allows me to apply patches directly from <code>mutt</code>, sending a
confirmation email to the person who sent me the patch.
<P>
<H2><A NAME="SECTION00453000000000000000">
Push</A>
</H2>
<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>
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
<code>.ssh/authorized_keys</code>. Then they run
<PRE>
% darcs push repouser@repo.server:repo/directory
</PRE>
<P>
<H2><A NAME="SECTION00454000000000000000">
Push --apply-as</A>
</H2>
<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>
Push <code>--apply-as</code> can run on either a local repository or one accessed
with ssh, but uses <code>sudo</code> to run a darcs apply command (having created
a patch bundle as in send) as another user. You can add the following line
in your sudoers file to allow the users to apply their patches to a
centralized repository:
<PRE>
ALL ALL = (repo-user) NOPASSWD: /usr/bin/darcs apply --all --repodir /repo/path*
</PRE>
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>
<H2><A NAME="SECTION00455000000000000000">
Sending signed patches by email</A>
</H2>
<P>
Most of the previous methods are a bit clumsy if you don't want to give
each person with write access to a repo 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>
This method is especially nice when combined with the <code>--test</code> 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>
Setting up darcs to run automatically in response to email is by far the
most complicated way to get patches from one repo to another... so it'll
take a few sections to explain how to go about it.
<P>
<H4><A NAME="SECTION00455010000000000000">
Security considerations</A>
</H4>
<P>
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 <code>--no-test</code> flag to darcs apply (and this is <SPAN CLASS="textit">not</SPAN>
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>
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>
<H4><A NAME="SECTION00455020000000000000">
Installing necessary programs</A>
</H4>
<P>
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').
<P>
<H4><A NAME="SECTION00455030000000000000">
Setting up a repository with its own user</A>
</H4>
<P>
To create a repository, as root run the `<code>darcs-createrepo</code>'. You
will be prompted for the email address of the repository and the location
of an existing copy of the repository. If your desired email is
``myproject@my.url'', this will create a user named ``myproject'' with a
home directory of <code>/var/lib/darcs/repos/myproject</code>. FIXME: I have no
idea if the darcs-createrepo program will even run on any system other than
debian. Success reports would be appreciated (or of course bug reports if
it fails).
<P>
The ``myproject'' user will be configured to run the darcs patcher on any
emails it receives. However, the patcher will bounce any emails which
aren't signed by a key in the
<code>/var/lib/darcs/repos/myproject/allowed_keys</code> gpg keyring (which is
empty). To give yourself access to this repository you will need to create
a gpg key. If you don't know about public key cryptography, take a look at
the gnupg manual.
<P>
<H4><A NAME="SECTION00455040000000000000">
Granting access to a repository</A>
</H4>
<P>
You create your gpg key by running (as your normal user):
<PRE>
% gpg --gen-key
</PRE>
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>
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):
<PRE>
% gpg --export "email@address" > /tmp/exported_key
</PRE>
And now we can add your key to the <code>allowed_keys</code>:
<PRE>
(as root)> gpg --keyring /var/lib/darcs/repos/myproject/allowed_keys \
--no-default-keyring --import /tmp/exported_key
</PRE>
You can repeat this process any number of times to authorize multiple users
to send patches to the repository.
<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:
<PRE>
% darcs send --sign http://your.computer/repos/myproject
</PRE>
You may want to add ``send sign'' to the file <code>_darcs/prefs/defaults</code>
so that you won't need to type <code>--sign</code> every time you want to
send...
<P>
If your gpg key is protected by a passphrase, then executing <code>send</code>
with the <code>--sign</code> option might give you the following error:
<PRE>
darcs failed: Error running external program 'gpg'
</PRE>
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 (<code>ENOENT</code>) causing <code>darcs</code> to
fail. To fix this, you will need to edit your <code>~/.gnupg/gpg.conf</code>
file and comment out or remove the line that says:
<PRE>
use-agent
</PRE>
If after commenting out or removing the <code>use-agent</code> 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 <code>use-agent</code> to <code>no-use-agent</code> to
disable it explicitly.
<P>
<H4><A NAME="SECTION00455050000000000000">
Setting up a sendable repository using procmail</A>
</H4>
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>
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 <code>/path/to/your/repo/_darcs/prefs</code> called <code>email</code>
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 <SPAN CLASS="MATH"><IMG
WIDTH="16" HEIGHT="28" ALIGN="MIDDLE" BORDER="0"
SRC="bigimg1.png"
ALT="$<$"></SPAN>droundy@abridgegame.org<SPAN CLASS="MATH"><IMG
WIDTH="16" HEIGHT="28" ALIGN="MIDDLE" BORDER="0"
SRC="bigimg2.png"
ALT="$>$"></SPAN>.''
<PRE>
% 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 repo. 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:
<PRE>
gpg --no-default-keyring \
--keyring /path/to/the/allowed_keys --recv-keys D3D5BCEC
</PRE>
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>
Finally, we add a few lines to your <code>.procmailrc</code>:
<PRE>
:0:
* ^TOmy darcs repo
|(umask 022; darcs apply --reply user@host.com \
--repodir /path/to/your/repo --verify /path/to/the/allowed_keys)
</PRE>
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 <code>--reply</code> 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>
I find that I need the ``umask 022'' in order to keep procmail from setting
the umask incorrectly, which causes the repository to no longer be
world-readable.
<P>
<H4><A NAME="SECTION00455060000000000000">
Checking if your e-mail patch was applied</A>
</H4>
<P>
After sending a patch with <code>darcs send</code>, 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 repo by pointing <code>darcs changes</code> at a remote repo:
<PRE>
darcs changes --last=10 --repo=http://abridgegame.org/repos/darcs
</PRE>
<P>
That shows you the last 10 changes in the remote repo. You can adjust the options given
to <code>changes</code> if a more advanced query is needed.
<P>
<H1><A NAME="SECTION00460000000000000000"></A>
<A NAME="disk-usage"></A>
<BR>
Reducing disk space usage
</H1>
<P>
A Darcs repository contains the patches that Darcs uses to store
history, the working directory, and a <SPAN CLASS="textit">pristine tree</SPAN> (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>
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>
<H2><A NAME="SECTION00461000000000000000">
Linking between repositories</A>
</H2>
<P>
A number of filesystems support <SPAN CLASS="textit">linking</SPAN> 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>
Whenever you invoke <code>darcs get</code> to copy a repository from a local
filesystem onto the same filesystem, Darcs will link patches whenever
possible.
<P>
In order to save time, <code>darcs get</code> 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 <SPAN CLASS="textit">relink</SPAN> files
between the two repositories.
<P>
Relinking is an asymmetric operation: you relink one repository (to
which you must have write access) to another repository, called the
<SPAN CLASS="textit">sibling</SPAN>. This is done with <code>darcs optimize --relink</code>, with
-the <code>--sibling</code> flag specifying the sibling.
<PRE>
$ cd /var/repos/darcs-unstable
$ darcs optimize --relink --sibling /var/repos/darcs
</PRE>
The <code>--sibling</code> 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>
Additional space savings can be achieved by relinking files in the
pristine tree (see below) by using the <code>--relink-pristine</code> flag.
However, doing this prevents Darcs from having precise timestamps on
the pristine files, which carries a moderate performance penalty.
<P>
<H2><A NAME="SECTION00462000000000000000">
Alternate formats for the pristine tree</A>
</H2>
<P>
By default, every Darcs repository contains a complete copy of the
<SPAN CLASS="textit">pristine tree</SPAN>, 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>
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>
Darcs automatically recognizes a repository with no pristine
tree. In order to create such a tree, specify the
<code>--no-pristine-tree</code> flag to <code>darcs initialize</code> or
<code>darcs get</code>. There is currently no way to switch an existing
repository to use no pristine tree.
<P>
The support for <code>--no-pristine-tree</code> 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>
<H1><A NAME="SECTION00500000000000000000"></A><A NAME="configuring"></A>
<BR>
Configuring darcs
</H1>
<P>
There are several ways you can adjust darcs' behavior to suit your needs.
The first is to edit files in the <code>_darcs/prefs/</code> 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 <code>~/.darcs/</code> directory. Finally, the behavior of some
darcs commands can be modified by setting appropriate environment
variables.
<P>
<H1><A NAME="SECTION00510000000000000000">
prefs</A>
</H1>
<P>
The <code>_darcs</code> directory contains a <code>prefs</code> directory. This
directory exists simply to hold user configuration settings specific to
this repository. The contents of this directory are intended to be
modifiable by the user, although in some cases a mistake in such a
modification may cause darcs to behave strangely.
<P>
<H4><A NAME="SECTION00510010000000000000"></A><A NAME="defaults"></A>
<BR>
defaults
</H4>
<P>
Default values for darcs commands can be configured on a per-repository
basis by editing (and possibly creating) the <code>_darcs/prefs/defaults</code>
file. Each line of this file has the following form:
<PRE>
COMMAND FLAG VALUE
</PRE>
where <code>COMMAND</code> is either the name of the command to which the default
applies, or <code>ALL</code> to indicate that the default applies to all commands
accepting that flag. The <code>FLAG</code> term is the name of the long argument
option without the ``<code>--</code>'', i.e. <code>verbose</code> rather than
<code>--verbose</code>. Finally, the <code>VALUE</code> option can be omitted if the
flag is one such as <code>verbose</code> that doesn't involve a value.
Each line only takes one flag. To set multiple defaults for the same
command (or for <code>ALL</code> commands), use multiple lines.
<P>
<TABLE CELLPADDING=3>
<TR><TD ALIGN="LEFT"><TT><code>~/.darcs/defaults</code></TT></TD>
<TD ALIGN="LEFT"><TT>provides defaults for this user account</TT></TD>
</TR>
<TR><TD ALIGN="LEFT"><TT><code>project/_darcs/prefs/defaults</code></TT></TD>
<TD ALIGN="LEFT"><TT>provides defaults for one project, overrules changes per user</TT></TD>
</TR>
</TABLE>
<P>
For example, if your system clock is bizarre, you could instruct darcs to
always ignore the file modification times by adding the following line to
your <code>_darcs/prefs/defaults</code> file. (Note that this would have to be
done for each repository!)
<PRE>
ALL ignore-times
</PRE>
<P>
If you never want to run a test when recording to a particular repository
(but still want to do so when running check on that repo), and like to name
all your patches ``Stupid patch'', you could use the following:
<PRE>
record no-test
record patch-name Stupid patch
</PRE>
<P>
If you would like a command to be run every time patches are recorded
in a particular repository (for example if you have one central
repository, that all developers contribute to), then you can set apply
to always run a command when apply is successful. For example, if you
need to make sure that the files in the repository have the correct
access rights you might use the following. There are two things
to note about using darcs this way:
<UL>
<LI>Without the second line you will get errors, because the sub
process that runs apply cannot prompt interactively.
</LI>
<LI>Whatever script is run by the post apply command should not be
be added to the repository with <code>darcs add</code>; doing so would
allow people to modify that file and then run arbitrary scripts on
your main repository, possibly damaging or violating security.
</LI>
</UL>
<PRE>
apply posthook chmod -R a+r *
apply run-posthook
</PRE>
<P>
There are some options which are meant specifically for use in
<code>_darcs/prefs/defaults</code>. One of them is <code>--disable</code>. As the name
suggests, this option will disable every command that got it as argument. So,
if you are afraid that you could damage your repositories by inadvertent use of
a command like amend-record, add the following line to
<code>_darcs/prefs/defaults</code>:
<PRE>
amend-record disable
</PRE>
<P>
Also, a global preferences file can be created with the name
<code>.darcs/defaults</code> in your home directory. Options present there will
be added to the repository-specific preferences.
If they conflict with repository-specific options, the repository-specific
ones will take precedence.
<P>
<H4><A NAME="SECTION00510020000000000000">
repos</A>
</H4>
The <code>_darcs/prefs/repos</code> file contains a list of repositories you have
pulled from or pushed to, and is used for autocompletion of pull and push
commands in bash. Feel free to delete any lines from this list that might
get in there, or to delete the file as a whole.
<P>
<H4><A NAME="SECTION00510030000000000000"></A><A NAME="author_prefs"></A>
<BR>
author
</H4>
The <code>_darcs/prefs/author</code> file contains the email address (or name) to
be used as the author when patches are recorded in this repository,
e.g. <code>David Roundy <droundy@abridgegame.org></code>. This
file overrides the contents of the environment variables
<code>$DARCS_EMAIL</code> and <code>$EMAIL</code>.
<P>
<H4><A NAME="SECTION00510040000000000000">
boring</A>
</H4>
The <code>_darcs/prefs/boring</code> file may contain a list of regular
expressions describing files, such as object files, that you do not expect
to add to your project. As an example, the boring file that I use with
my darcs repository is:
<PRE>
\.hi$
\.o$
^\.[^/]
^_
~$
(^|/)CVS($|/)
</PRE>
A newly created repository has a longer boring file that
includes many common source control, backup, temporary, and compiled files.
<P>
You may want to have the boring file under version
control. To do this you can use darcs setpref to set the value
``boringfile'' to the name of your desired boring file (e.g. ``darcs
setpref boringfile .boring'', where .boring is the repository path of a file
that has been
darcs added to your repository). The boringfile pref overrides
<code>_darcs/prefs/boring</code>, so be sure to copy that file to the boringfile.
<P>
You can also set up a ``boring'' regexps
file in your home directory, named <code>~/.darcs/boring</code>, which will be
used with all of your darcs repositories.
<P>
Any file whose repository path (such as <code>manual/index.html</code>) matches any of
the boring regular expressions is considered boring. The boring file is
used to filter the files provided to darcs add, to allow you to use a
simple ``darcs add newdir newdir/*'' without accidentally adding a bunch of
object files. It is also used when the <code>--look-for-adds</code> flag is
given to whatsnew or record.
<P>
<H4><A NAME="SECTION00510050000000000000">
binaries</A>
</H4>
The <code>_darcs/prefs/binaries</code> file may contain a list of regular
expressions describing files that should be treated as binary files rather
than text files. You probably will want to have the binaries file under
version control. To do this you can use darcs setpref to set the value
``binariesfile'' to the name of your desired binaries file (e.g. ``darcs
setpref binariesfile ./.binaries'', where .binaries is a file that has been
darcs added to your repository). As with the boring file, you can also set
up a <code>~/.darcs/binaries</code> file if you like.
<P>
<H4><A NAME="SECTION00510060000000000000">
email</A>
</H4>
The <code>_darcs/prefs/email</code> file is used to provide the e-mail address for your
repo that others will use when they <code>darcs send</code> a patch back to you.
The contents of the file should simply be an e-mail address.
<P>
<H4><A NAME="SECTION00510070000000000000">
motd</A>
</H4>
The <code>_darcs/prefs/motd</code> file may contain a ``message of the day''
which will be displayed to users who get or pull from the repo without the
<code>--quiet</code> option.
<P>
<H1><A NAME="SECTION00520000000000000000">
Environment variables</A>
</H1>
<P>
There are a few environment variables whose contents affect darcs'
behavior.
<P>
<H4><A NAME="SECTION00520010000000000000">
DARCS_EMAIL</A>
</H4>
The DARCS_EMAIL environment variable determines the ``author'' name used
by darcs when recording if no <code>_darcs/prefs/author</code> exists. If
DARCS_EMAIL is undefined, the contents of the EMAIL environment variable
are used.
<P>
<H4><A NAME="SECTION00520020000000000000">
DARCS_EDITOR</A>
</H4>
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 <code>vi</code>, <code>emacs</code>, <code>emacs -nw</code> and
<code>nano</code> in that order.
<P>
<H4><A NAME="SECTION00520030000000000000">
DARCS_TMPDIR</A>
</H4>
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 <code>/tmp</code> and if <code>/tmp</code> doesn't exist,
it'll put the temporaries in <code>_darcs</code>.
<P>
This is very helpful, for example, when recording with a test suite that
uses MPI, in which case using <code>/tmp</code> to hold the test copy is no good,
as <code>/tmp</code> isn't shared over NFS and thus the <code>mpirun</code> call will
fail, since the binary isn't present on the compute nodes.
<P>
<H4><A NAME="SECTION00520040000000000000">
HOME</A>
</H4>
HOME is used to find the per-user prefs directory, which is located at
<code>$HOME/.darcs</code>.
<P>
<H4><A NAME="SECTION00520050000000000000">
TERM</A>
</H4>
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.
<P>
<H4><A NAME="SECTION00520060000000000000">
SSH_PORT</A>
</H4>
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).
<P>
<H4><A NAME="SECTION00520070000000000000"></A>
<A NAME="darcsssh"></A>
<BR>
DARCS_SSH
</H4>
The DARCS_SSH environment variable defines the command that darcs will use
when asked to run ssh. This command is <SPAN CLASS="textit">not</SPAN> 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.
<P>
<H4><A NAME="SECTION00520080000000000000">
DARCS_SCP and DARCS_SFTP</A>
</H4>
The DARCS_SCP and DARCS_SFTP environment variables define the
commands that darcs will use when asked to run scp or sftp. Note that
scp and sftp is how darcs accesses repositories whose URL is of the
form <code>user@foo.org:foo</code> or <code>foo.org:foo</code>. 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
<SPAN CLASS="textit">not</SPAN> 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.
<P>
<H4><A NAME="SECTION00520090000000000000">
DARCS_PROXYUSERPWD</A>
</H4>
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 <SPAN CLASS="textit">username:password</SPAN>.
<P>
<H4><A NAME="SECTION005200100000000000000">
DARCS_GET_FOO, DARCS_MGET_FOO and DARCS_APPLY_FOO</A>
</H4>
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.
<P>
This method overrides all other ways of getting <code>foo://xxx urls</code>.
<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>
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 <SPAN CLASS="textit">not</SPAN> 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 filename but not the path,
the APPLY command will be called with a darcs patchfile piped into
its standard input. Example:
<P>
<PRE>
wget -q
</PRE>
<P>
<H4><A NAME="SECTION005200110000000000000">
DARCS_MGETMAX</A>
</H4>
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.
<P>
<H4><A NAME="SECTION005200120000000000000">
DARCS_WGET</A>
</H4>
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>
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>
wget -q
</PRE>
<P>
Darcs will append <code>-i</code> 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 <code>wget</code> with this
environment variable, but it must support the <code>-i</code> option in the same way.
<P>
These commands are <SPAN CLASS="textit">not</SPAN> interpreted by a shell, so you cannot use shell
meta-characters.
<P>
<H1><A NAME="SECTION00530000000000000000">
Highlighted output</A>
</H1>
<P>
If the terminal understands ANSI color codes,
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 understands ANSI colors, like <code>less -R</code>,
darcs can be forced to always 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.
<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>
<H1><A NAME="SECTION00540000000000000000">
Character escaping and non-ASCII character encodings</A>
</H1>
<P>
Darcs needs to escape certain characters when printing patch contents to a terminal.
Characters like <SPAN CLASS="textit">backspace</SPAN> 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>
By default darcs will only allow printable 7-bit ASCII characters (including space),
and the two control characters <SPAN CLASS="textit">tab</SPAN> and <SPAN CLASS="textit">newline</SPAN>.
(See the last paragraph in this section for a way to tailor this behavior.)
All other octets are printed in quoted form (as <code>^<control letter></code> or <code>\<hex code></code>).
<P>
Darcs has some limited support for locales.
If the systems 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 does curently 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>
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 Latin1
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>
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 <SPAN CLASS="textit">all</SPAN> escaping,
including the special escaping of any line ending spaces,
will be turned off by this setting.
<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>
<H1><A NAME="SECTION00600000000000000000">
Best practices</A>
</H1>
<P>
<H1><A NAME="SECTION00610000000000000000">
Introduction</A>
</H1>
<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>
<H1><A NAME="SECTION00620000000000000000">
Creating patches</A>
</H1>
<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>
In a single darcs repository you can think of two ``versions'' of the source tree.
They are called the <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN> trees.
<SPAN CLASS="textit">Working</SPAN> is your normal source tree, with or without darcs alongside.
The only thing that makes it part of a darcs repository
is the <code>_darcs</code> directory in its root.
<SPAN CLASS="textit">Pristine</SPAN> 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 use the
term <EM>changeset</EM> instead of <EM>patch</EM>).<A NAME="tex2html9"
HREF="#foot2000"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">1</SPAN></SUP></A> Darcs will create and store these patches
based on the changes you make in <SPAN CLASS="textit">working</SPAN>.
<P>
<H2><A NAME="SECTION00621000000000000000">
Changes</A>
</H2>
If <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN> are the same,
there are ``no changes'' in the repository.
Changes can be introduced (or removed) by editing the files in <SPAN CLASS="textit">working</SPAN>.
They can also be caused by darcs commands,
which can modify <SPAN CLASS="textit">both</SPAN> <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN>.
It is important to understand for each darcs command
how it modifies <SPAN CLASS="textit">working</SPAN>, <SPAN CLASS="textit">pristine</SPAN> or both of them.
<P>
<code>whatsnew</code> (as well as <code>diff</code>) can show
the difference between <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN> to you.
It will be shown as a difference in <SPAN CLASS="textit">working</SPAN>.
In advanced cases it need <SPAN CLASS="textit">not</SPAN> be <SPAN CLASS="textit">working</SPAN> that has changed;
it can just as well have been <SPAN CLASS="textit">pristine</SPAN>, or both.
The important thing is the difference and what darcs can do with it.
<P>
<H2><A NAME="SECTION00622000000000000000">
Keeping or discarding changes</A>
</H2>
If you have a difference in <SPAN CLASS="textit">working</SPAN>, you do two things
with it: <code>record</code> it to keep it, or <code>revert</code> it to lose the changes.<A NAME="tex2html10"
HREF="#foot369"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">2</SPAN></SUP></A>
<P>
If you have a difference between <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN>--for example after editing some files in <SPAN CLASS="textit">working</SPAN>--<code>whatsnew</code> will show some ``unrecorded changes''.
To save these changes, use <code>record</code>.
It will create a new patch in <SPAN CLASS="textit">pristine</SPAN> with the same changes,
so <SPAN CLASS="textit">working</SPAN> and <SPAN CLASS="textit">pristine</SPAN> are no longer different.
To instead undo the changes in <SPAN CLASS="textit">working</SPAN>, use <code>revert</code>.
It will modify the files in <SPAN CLASS="textit">working</SPAN> to be the same as in <SPAN CLASS="textit">pristine</SPAN>
(where the changes do not exist).
<P>
<H2><A NAME="SECTION00623000000000000000">
Unrecording changes</A>
</H2>
<code>unrecord</code> 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>
However, darcs does not prevent you from unrecording a patch that
has been copied to another repository. Be aware of this danger!
<P>
If you <code>unrecord</code> a patch, that patch will be deleted from <SPAN CLASS="textit">pristine</SPAN>.
This will cause <SPAN CLASS="textit">working</SPAN> to be different from <SPAN CLASS="textit">pristine</SPAN>,
and <code>whatsnew</code> to report unrecorded changes.
The difference will be the same as just before that patch was <code>record</code>ed.
Think about it.
<code>record</code> examines what's different with <SPAN CLASS="textit">working</SPAN>
and constructs a patch with the same changes in <SPAN CLASS="textit">pristine</SPAN>
so they are no longer different.
<code>unrecord</code> deletes this patch;
the changes in <SPAN CLASS="textit">pristine</SPAN> disappear and the difference is back.
<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>
If the whole change was wrong it can be discarded from <SPAN CLASS="textit">working</SPAN> too,
with <code>revert</code>.
<code>revert</code> will update <SPAN CLASS="textit">working</SPAN> to the state of <SPAN CLASS="textit">pristine</SPAN>,
in which the changes do no longer exist after the patch was deleted.
<P>
Keep in mind that the patches are your history,
so deleting them with <code>unrecord</code> makes it impossible to track
what changes you <SPAN CLASS="textit">really</SPAN> 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>
All patches are global,
so don't <SPAN CLASS="textit">ever</SPAN> 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 <SPAN CLASS="textit">all</SPAN> 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>
<H2><A NAME="SECTION00624000000000000000">
Special patches and pending</A>
</H2>
<P>
The patches described in the previous sections have mostly been hunks.
A <SPAN CLASS="textit">hunk</SPAN> 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 <SPAN CLASS="textit">adddir</SPAN> and <SPAN CLASS="textit">addfile</SPAN>
which add new directories and files,
and <SPAN CLASS="textit">replace</SPAN>
which does a search-and-replace on tokens in files.
<P>
Hunks are always calculated in place with a diff algorithm
just before <code>whatsnew</code> or <code>record</code>.
But other types of primitive patches need to be explicitly created
with a darcs command.
They are kept in <SPAN CLASS="textit">pending</SPAN><A NAME="tex2html11"
HREF="#foot2001"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">3</SPAN></SUP></A>until they are either recorded or reverted.
<P>
<SPAN CLASS="textit">Pending</SPAN> can be thought of as a special extension of <SPAN CLASS="textit">working</SPAN>.
When you issue, e.g., a darcs <code>replace</code> command,
the replace is performed on the files in <SPAN CLASS="textit">working</SPAN>
and at the same time a replace patch is put in <SPAN CLASS="textit">pending</SPAN>.
Patches in <SPAN CLASS="textit">pending</SPAN> describe special changes made in <SPAN CLASS="textit">working</SPAN>.
The diff algorithm will fictively apply these changes to <SPAN CLASS="textit">pristine</SPAN>
before it compares it to <SPAN CLASS="textit">working</SPAN>,
so all lines in <SPAN CLASS="textit">working</SPAN> that are changed by a <code>replace</code> command
will also be changed in <SPAN CLASS="textit">pending</SPAN><SPAN CLASS="MATH"><IMG
WIDTH="31" HEIGHT="11" ALIGN="MIDDLE" BORDER="0"
SRC="bigimg3.png"
ALT="$+$"></SPAN><SPAN CLASS="textit">pristine</SPAN>
when the hunks are calculated.
That's why no hunks with the replaced lines will be shown by <code>whatsnew</code>;
it only shows the replace patch in <SPAN CLASS="textit">pending</SPAN> responsible for the change.
<P>
If a special patch is recorded, it will simply be moved to <SPAN CLASS="textit">pristine</SPAN>.
If it is instead reverted, it will be deleted from <SPAN CLASS="textit">pending</SPAN>
and the accompanying change will be removed from <SPAN CLASS="textit">working</SPAN>.
<P>
Note that reverting a patch in pending is <SPAN CLASS="textit">not</SPAN> the same as
simply removing it from pending.
It actually applies the inverse of the change to <SPAN CLASS="textit">working</SPAN>.
Most notable is that reverting an addfile patch
will delete the file in <SPAN CLASS="textit">working</SPAN> (the inverse of adding it).
So if you add the wrong file to darcs by mistake,
<SPAN CLASS="textit">don't</SPAN> <code>revert</code> the addfile.
Instead first rename the file, revert, and then rename it back.
<P>
<H1><A NAME="SECTION00630000000000000000">
Using patches</A>
</H1>
<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>
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 depended upon patches are there.
Patches can be removed from a repository in any order,
as long as no remaining patches depend on them.
<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>
<H2><A NAME="SECTION00631000000000000000">
Dependencies</A>
</H2>
<P>
There are two kinds of dependencies:
implicit dependencies and explicit dependencies.
<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 NAME="tex2html12"
HREF="#foot420"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">4</SPAN></SUP></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>
Explicit dependencies can be created if you give the <code>--ask-deps</code> option to <code>darcs record</code>.
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>
<H2><A NAME="SECTION00632000000000000000">
Branches: just normal repositories</A>
</H2>
<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>
Branches are <SPAN CLASS="textit">very</SPAN> useful in darcs.
They are in fact <SPAN CLASS="textit">necessary</SPAN> if you want to do more than only simple work.
When you <code>get</code> 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>
You create new branches (i.e., clone repositories)
with the <code>get</code> and <code>put</code> commands.
<P>
<H2><A NAME="SECTION00633000000000000000">
Moving patches around--no versions</A>
</H2>
<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 <SPAN CLASS="textit">won't</SPAN> 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 NAME="tex2html13"
HREF="#foot2002"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">5</SPAN></SUP></A>
<P>
Patches are added to a repository with <code>pull</code>
and removed from the repositories with <code>unpull</code>.
Don't confuse these two commands with <code>record</code> and <code>unrecord</code>,
which constructs and deconstructs patches.
<P>
It is important not to lose patches when (re)moving them around.
<code>pull</code> needs a source repository to copy the patch from,
whereas <code>unpull</code> just erases the patch.
Beware that if you unpull <SPAN CLASS="textit">all</SPAN> copies of a patch
it is completely lost--forever.
Therefore you should work with branches when you unpull patches.
The <code>unpull</code> command can wisely be disabled in a dedicated main repository
by adding <code>unpull disable</code> to the repository's defaults file.
<P>
For convenience, there is a <code>push</code> command.
It works like <code>pull</code> but in the other direction.
It also differs from <code>pull</code> 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>
<H2><A NAME="SECTION00634000000000000000">
Tags--versions</A>
</H2>
<P>
While <code>pull</code> and <code>unpull</code> 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 <code>tag</code>,
and it records a tag in the current repository.
<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 NAME="tex2html14"
HREF="#foot429"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">6</SPAN></SUP></A>Darcs can recognize if a patch is as a tag;
tags are sometimes treated specially by darcs commands.
<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>
With the option <code>--tag</code> to <code>get</code> you can easily get
a named version in the repository
as a new branch.
<P>
<H2><A NAME="SECTION00635000000000000000">
Conflicts</A>
</H2>
<P>
This part of darcs becomes a bit complicated,
and the description given here is slightly simplified.
<P>
Conflicting patches are created when
you record changes to the same line in two different repositories.
Same line does <SPAN CLASS="textit">not</SPAN> mean the same line number and file name,
but the same line added by a common depended upon patch.
<P>
Contrary to many other merging tools,
darcs considers two patches making the <SPAN CLASS="textit">same</SPAN> change to be a conflict.
In fact, darcs doesn't even look at the contents of the conflicting lines.
If you think this is wrong, think about two different patches
each adding a new keyword and also changing the line
``<code>#define NUM_OF_KEYWORDS 17</code>''
to
``<code>#define NUM_OF_KEYWORDS 18</code>''.
<P>
A conflict <SPAN CLASS="textit">happens</SPAN> 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 <SPAN CLASS="textit">working</SPAN> (and <SPAN CLASS="textit">pristine</SPAN>).
The conflict can be thought of as
two patches telling darcs different things about what a file should look like.
<P>
Darcs escapes this problem
by ignoring those parts<A NAME="tex2html15"
HREF="#foot436"><SUP><SPAN CLASS="arabic">5</SPAN>.<SPAN CLASS="arabic">7</SPAN></SUP></A>of the patches that conflict.
They are ignored in <SPAN CLASS="textit">both</SPAN> 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>
Darcs can mark a conflict for you in <SPAN CLASS="textit">working</SPAN>.
This is done with <code>resolve</code> (which isn't a very good name).
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>
When you pull patches,
darcs automatically performs a <code>resolve</code> for you if a conflict happens.
You can remove the markup with <code>revert</code>,
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 <code>resolve</code>.
<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 <SPAN CLASS="textit">also</SPAN> an unrecorded change,
it will get mixed in with your unrecorded changes.
There is no guarantee you can revert <code>only</code> the markup after this,
and <code>resolve</code> will not be able to redo this markup later if you remove it.
It is good practice to record important changes before pulling.
<P>
<code>resolve</code> can't mark complicated conflicts.
In that case you'll have to use <code>darcs diff</code> and other commands
to understand what the conflict is all about.
If for example two conflicting patches create the same file,
<code>resolve</code> will pick just one of them,
and no delimiters are inserted.
So watch out if darcs tells you about a conflict.
<P>
<code>resolve</code> can also be used to check for unresolved conflicts.
If there are none, darcs replies ``No conflicts to resolve''.
While <code>pull</code> reports when a conflict happens,
<code>unpull</code> and <code>get</code> don't.
<P>
<H2><A NAME="SECTION00636000000000000000">
Resolving conflicts</A>
</H2>
<P>
A conflict is resolved
(not marked, as with the command <code>resolve</code>)
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 <code>resolve</code> (or <code>pull</code>).
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>
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>
If you want to back out and wait with the conflict,
you can <code>unpull</code> the conflicting patch you just pulled.
Before you can do that you have to <code>revert</code> the conflict markups
that <code>pull</code> inserted when the conflict happened.
<P>
<H1><A NAME="SECTION00640000000000000000"></A>
<A NAME="darcs-development-practices"></A>
<BR>
Distributed development with one primary developer
</H1>
<P>
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, <code>darcs send</code> is ideal, since the barrier for
contributions is very low, which helps encourage contributors.
<P>
One could simply set the <code>_darcs/prefs/email</code> 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
``<code>Davids Darcs Repo <droundy@abridgegame.org></code>''. My .procmailrc
file on the server has the following rule:
<PRE>
:0:
* ^TODavids Darcs Repo
|(umask 022; darcs apply --reply darcs-devel@abridgegame.org \
--repodir /path/to/repo --verify /path/to/allowed_keys)
</PRE>
This causes darcs apply to be run on any emails sent to ``Davids Darcs
Repo''. Apply 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>
The central darcs repository contains the following values in its
<code>_darcs/prefs/defaults</code>:
<PRE>
apply test
apply verbose
apply happy-forwarding
</PRE>
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 <code>darcs-devel</code>.
<P>
On my development computer, I have in my <code>.muttrc</code> the following
alias, which allows me to easily apply patches that I get via email
directly to my darcs working directory:
<PRE>
macro pager A "<pipe-entry>(umask 022; darcs apply --no-test -v --repodir ~/darcs)"
</PRE>
<P>
<H1><A NAME="SECTION00650000000000000000"></A>
<A NAME="dft-development-practices"></A>
<BR>
Development by a small group of developers in one office
</H1>
<P>
This section describes the development method used for the density
functional theory code DFT++, which is available at
<code>http://dft.physics.cornell.edu/dft</code>.
<P>
We have a number of workstations which all mount the same <code>/home</code> 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 <code>.ssh/allowed_keys</code>, and we commit patches to this
repository using darcs push. As in Section <A HREF="#darcs-development-practices"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
SRC="./crossref.png"></A>,
we have the central repository set to run the test suite before the push goes
through.
<P>
Note that no one ever runs as the dft user.
<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 <code>$DARCS_TMPDIR</code> environment vari