File: node6.html

package info (click to toggle)
darcs 2.0.2-3
links: PTS
area: main
in suites: lenny
size: 6,400 kB
ctags: 1,048
sloc: haskell: 24,937; perl: 9,736; sh: 3,369; ansic: 1,913; makefile: 17; xml: 14
file content (921 lines) | stat: -rw-r--r-- 37,095 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!--Converted with LaTeX2HTML 2002-2-1 (1.71)
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>Best practices</TITLE>
<META NAME="description" CONTENT="Best practices">
<META NAME="keywords" CONTENT="darcs">
<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="darcs.css">

<LINK REL="next" HREF="node7.html">
<LINK REL="previous" HREF="node5.html">
<LINK REL="up" HREF="darcs.html">
<LINK REL="next" HREF="node7.html">
</HEAD>

<BODY >

<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html411"
  HREF="node7.html">
<IMG WIDTH="22" HEIGHT="22" title="Next"  ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="./next.png"></A> 
<A NAME="tex2html407"
  HREF="darcs.html">
<IMG WIDTH="22" HEIGHT="22" title="Up"  ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="./up.png"></A> 
<A NAME="tex2html401"
  HREF="node5.html">
<IMG WIDTH="22" HEIGHT="22" title="Previous"  ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="./prev.png"></A> 
<A NAME="tex2html409"
  HREF="node1.html">
<IMG WIDTH="22" HEIGHT="22" title="Contents"  ALIGN="BOTTOM" BORDER="0" ALT="contents"
 SRC="./contents.png"></A>  
<BR>
<B> Next:</B> <A NAME="tex2html412"
  HREF="node7.html">Darcs commands</A>
<B> Up:</B> <A NAME="tex2html408"
  HREF="darcs.html">Darcs 2.0.2 (unknown) Darcs</A>
<B> Previous:</B> <A NAME="tex2html402"
  HREF="node5.html">Configuring darcs</A>
 &nbsp; <B>  <A NAME="tex2html410"
  HREF="node1.html">Contents</A></B> 
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>

<UL CLASS="ChildLinks">
<LI><A NAME="tex2html413"
  HREF="node6.html#SECTION00610000000000000000">Introduction</A>
<LI><A NAME="tex2html414"
  HREF="node6.html#SECTION00620000000000000000">Creating patches</A>
<UL>
<LI><A NAME="tex2html415"
  HREF="node6.html#SECTION00621000000000000000">Changes</A>
<LI><A NAME="tex2html416"
  HREF="node6.html#SECTION00622000000000000000">Keeping or discarding changes</A>
<LI><A NAME="tex2html417"
  HREF="node6.html#SECTION00623000000000000000">Unrecording changes</A>
<LI><A NAME="tex2html418"
  HREF="node6.html#SECTION00624000000000000000">Special patches and pending</A>
</UL>
<BR>
<LI><A NAME="tex2html419"
  HREF="node6.html#SECTION00630000000000000000">Using patches</A>
<UL>
<LI><A NAME="tex2html420"
  HREF="node6.html#SECTION00631000000000000000">Dependencies</A>
<LI><A NAME="tex2html421"
  HREF="node6.html#SECTION00632000000000000000">Branches: just normal repositories</A>
<LI><A NAME="tex2html422"
  HREF="node6.html#SECTION00633000000000000000">Moving patches around--no versions</A>
<LI><A NAME="tex2html423"
  HREF="node6.html#SECTION00634000000000000000">Tags--versions</A>
<LI><A NAME="tex2html424"
  HREF="node6.html#SECTION00635000000000000000">Conflicts</A>
<LI><A NAME="tex2html425"
  HREF="node6.html#SECTION00636000000000000000">Resolving conflicts</A>
</UL>
<BR>
<LI><A NAME="tex2html426"
  HREF="node6.html#SECTION00640000000000000000">Distributed development with one primary developer</A>
<LI><A NAME="tex2html427"
  HREF="node6.html#SECTION00650000000000000000">Development by a small group of developers in one office</A>
<LI><A NAME="tex2html428"
  HREF="node6.html#SECTION00660000000000000000">Personal development</A>
<UL>
<LI><A NAME="tex2html429"
  HREF="node6.html#SECTION00661000000000000000">Private patches</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>

<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 systems use the
	term <EM>changeset</EM> instead of <EM>patch</EM>).<A NAME="tex2html9"
  HREF="footnode.html#foot2392"><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="footnode.html#foot428"><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="footnode.html#foot2393"><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="17" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img3.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 use <code>remove</code>, which cancels out the addfile in pending.

<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 patches depended upon are there.
Patches can be removed from a repository in any order,
as long as no remaining patches depend on them.

<P>
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="footnode.html#foot479"><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="footnode.html#foot2394"><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>obliterate</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>obliterate</code> just erases the patch.
Beware that if you obliterate <SPAN  CLASS="textit">all</SPAN> copies of a patch
it is completely lost--forever.
Therefore you should work with branches when you obliterate patches.
The <code>obliterate</code> command can wisely be disabled in a dedicated main repository
by adding <code>obliterate 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>obliterate</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="footnode.html#foot488"><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>
If you are using a darcs-2 repository (Section <A HREF="node7.html#initialize"><IMG  ALIGN="BOTTOM" BORDER="1" ALT="[*]"
 SRC="./crossref.png"></A>),
darcs does <SPAN  CLASS="textit">not</SPAN> consider two patches making the <SPAN  CLASS="textit">same</SPAN> change to be a
conflict, much in the same fashion as other version control systems.
(The caveat here is two non-identical patches with some identical
changes may conflict.  For the most part, darcs should just do what you
expect).

<P>
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="footnode.html#foot497"><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&nbsp;A changes the line ``FIXME'' to ``FIXED'',
and patch&nbsp;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>mark-conflicts</code>.
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>mark-conflicts</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>mark-conflicts</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 <SPAN  CLASS="textit">only</SPAN> 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>mark-conflicts</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>mark-conflicts</code> will pick just one of them,
and no delimiters are inserted.
So watch out if darcs tells you about a conflict.

<P>
<code>mark-conflicts</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>obliterate</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>mark-conflicts</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>mark-conflicts</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>obliterate</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 &lt;droundy@abridgegame.org&gt;</code>''.  My
<code>.procmailrc</code>
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 email sent to ``Davids Darcs
Repo''.
<code>apply</code> 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 "&lt;pipe-entry&gt;(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
<code>darcs push</code>.  As in Section&nbsp;<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 variable to <code>~/tmp</code>.

<P>
Note that even though there are only four active developers at the moment,
the distributed nature of darcs still plays a large role.  Each developer
works on a feature until it is stable, a process that often takes quite a
few patches, and only once it is stable does he
<code>push</code> to the central repository.

<P>

<H1><A NAME="SECTION00660000000000000000">
Personal development</A>
</H1>

<P>
It's easy to have several personal development trees using darcs, even
when working on a team or with shared code.  The number and method of
using each personal tree is limited only by such grand limitations as:
your disk space, your imagination, available time, etc.

<P>
For example, if the central darcs repository for your development team
is <SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img4.png"
 ALT="$R_{c}$"></SPAN>, you can create a local working directory for feature
<SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN>.  This local working directory contains a full copy of <SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>
(as of the time of the ``darcs get'' operation) and can be denoted
<SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img7.png"
 ALT="$R_1$"></SPAN>.  In the midst of working on feature <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN>, you realize it
requires the development of a separate feature <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN>.  Rather than
intermingling <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN> and <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN> in the same working tree, you can create
a new working tree for working on <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN>, where that working tree
contains the repository <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img9.png"
 ALT="$R_2$"></SPAN>.

<P>
While working on <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN>, other developers may have made other changes;
these changes can be retrieved on a per-patch selection basis by
periodic ``darcs pull'' operations.

<P>
When your work on <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN> is completed, you can publish it for the use
of other developers by a ``darcs push'' (or ``darcs send'') from <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img9.png"
 ALT="$R_2$"></SPAN>
to <SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>.  Independently of the publishing of <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN>, you can merge
your <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN> work into your <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN> working tree by a ``darcs pull <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img9.png"
 ALT="$R_2$"></SPAN>''
in the <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img7.png"
 ALT="$R_1$"></SPAN> development tree (or ``darcs push'' from <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img9.png"
 ALT="$R_2$"></SPAN> to <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img7.png"
 ALT="$R_1$"></SPAN>).

<P>
When your work on <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN> is completed, you publish it as well by a
``darcs push'' from <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img7.png"
 ALT="$R_1$"></SPAN> to <SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>.  

<P>
Your local feature development efforts for <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img5.png"
 ALT="$f_1$"></SPAN> or <SPAN CLASS="MATH"><IMG
 WIDTH="19" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img8.png"
 ALT="$f_2$"></SPAN> can each
consist of multiple patches.  When pushing or pulling to other trees,
these patches can either all be selected or specific patches can be
selected.  Thus, if you introduce a set of debugging calls into the
code, you can commit the debugging code in a distictly separate patch
(or patches) that you will not push to <SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>.

<P>

<H2><A NAME="SECTION00661000000000000000">
Private patches</A>
</H2>

<P>
As discussed in the section above, a developer may have various
changes to their local development repositories that they do not ever
wish to publish to a group repository (e.g. personal debugging code),
but which they would like to keep in their local repository, and
perhaps even share amongst their local repositories.

<P>
This is easily done via darcs, since those private changes can be
committed in patches that are separate from other patches; during the
process of pushing patches to the common repository (<SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>), the
developer is queried for which patches should be moved to (<SPAN CLASS="MATH"><IMG
 WIDTH="23" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img6.png"
 ALT="$R_c$"></SPAN>) on a
patch-by-patch basis.

<P>
The <code>--complement</code> flag for the ``darcs pull'' operation can
further simplify this effort.  If the developer copies (via ``darcs
push'' or ``darcs pull'') all private patches into a special
repository/working tree (<SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img10.png"
 ALT="$R_p$"></SPAN>), then those patches are easily
disregarded for pulling by adding <code>--complement</code> to the ``darcs
pull'' line and listing <SPAN CLASS="MATH"><IMG
 WIDTH="24" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img10.png"
 ALT="$R_p$"></SPAN> after the primary source repository.

<P>
The <code>--complement</code> flag is only available for ``darcs pull'', and
not ``darcs push'' or ``darcs send'', requiring the user to have pull
access to the target repository.  While the actual public repository
is often not shared in this manner, it's simple to create a local
version of the public repository to act as the staging area for that
public repository.

<P>
The following example extends the two feature addition example in the
previous section using a local staging repository (<SPAN CLASS="MATH"><IMG
 WIDTH="21" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
 SRC="img11.png"
 ALT="$R_l$"></SPAN>) and a
private patch repository:

<P>
<PRE>
$ cd working-dir
$ darcs get http://server/repos/Rc Rl

$ darcs get Rl R1
$ cd R1
...development of f1
$ darcs record -m'p1: f1 initial work'
...
$ darcs record -m'p2: my debugging tracepoints'
...

$ cd ..
$ darcs get http://server/repos/Rc R2
$ cd R2
$ darcs pull -p p2 ../R1
... development of f2
$ darcs record -m'p3: f2 finished'

$ cd ..
$ darcs get Rl Rp
$ cd Rp
$ darcs pull -p p2 ../R2

$ cd ../Rl
$ darcs pull --complement ../R2 ../Rp
$ darcs send
... for publishing f2 patches to Rc

$ cd ../R1
$ darcs pull ../R2
... updates R1 with f2 changes from R2
... more development of f1
$ darcs record -m'p4: f1 feature finished.'

$ cd ../Rl
$ darcs pull --complement ../R1 ../Rp
$ darcs send
</PRE>

<P>

<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html411"
  HREF="node7.html">
<IMG WIDTH="22" HEIGHT="22" title="Next"  ALIGN="BOTTOM" BORDER="0" ALT="next"
 SRC="./next.png"></A> 
<A NAME="tex2html407"
  HREF="darcs.html">
<IMG WIDTH="22" HEIGHT="22" title="Up"  ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="./up.png"></A> 
<A NAME="tex2html401"
  HREF="node5.html">
<IMG WIDTH="22" HEIGHT="22" title="Previous"  ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="./prev.png"></A> 
<A NAME="tex2html409"
  HREF="node1.html">
<IMG WIDTH="22" HEIGHT="22" title="Contents"  ALIGN="BOTTOM" BORDER="0" ALT="contents"
 SRC="./contents.png"></A>  
<BR>
<B> Next:</B> <A NAME="tex2html412"
  HREF="node7.html">Darcs commands</A>
<B> Up:</B> <A NAME="tex2html408"
  HREF="darcs.html">Darcs 2.0.2 (unknown) Darcs</A>
<B> Previous:</B> <A NAME="tex2html402"
  HREF="node5.html">Configuring darcs</A>
 &nbsp; <B>  <A NAME="tex2html410"
  HREF="node1.html">Contents</A></B> </DIV>
<!--End of Navigation Panel-->
<ADDRESS>
David Roundy
2008-06-23
</ADDRESS>
</BODY>
</HTML>