gistfile1.txt

New patches:

[Rev #1: Front page.
[email protected]**20090413195159] hunk ./Front\32\Page.page 3
-Darcs is a free, open source, source code management system with many
-fabulous features:
+Darcs is a free, open source, version control system (VCS). Darcs stands out
+for its ability to [reorder patches](Patch Reordering) in a repository. This
+gives darcs several valuable features:
+
+- **Flexible** - With darcs, you can apply patches in any order. If Jane
+implements feature A and then feaure B, Dick can apply the patches for feature
+B only, and later decide if he wants A or not. With darcs you can cherry pick,
+branch, merge changes in any order you like and Darcs will always know how to
+do it. *With Darcs, if you apply the same patches in a different order you will
+always get the same result*.
+
+
+- **Distributed** - You don't need a central server. You can save, commit, branch
+and merge entirely offline. Alice and Bob can work on feature X  and then Y while
+Charlie and Denise work on feature Z. Then Ellen can merge Y and Z and ignore X.
+
+- **Human Friendly** - Most VCSs impose a historical orer on changes. But humans
+don't work like that. We don't think of two different changes that implement
+different features as having a particular order. Well, neither does Darcs. In
+Darcs, you give a name to each patch (e.g. 'feature X') and you tell Darcs which
+set of patches you want (e.g. "I'd like feature Y and Z but not X"). Darcs will
+know what to do with this. This makes some "complicated" mergers not complicated
+at all in Darcs.
+
+- **Smart** - Darcs understands dependencies between patches. You can't delete
+a file before you add it. You can't rename a function before you write it. The
+rules Darcs uses are simple but powerful. Darcs understands when two patches
+can be reordered and when they can't. Darcs uses dependencies to know when there
+is a conflict (e.g. Bob can't rename file foo.txt to bar.txt if Alice already
+renamed it to something else). This means that when Darcs finds a conflict, it
+is likely to be a genuine conflict that requires a human to resolve (Alice and
+Bob must settle on a name for the file).
hunk ./Front\32\Page.page 36
-- **[Distributed]()** - Every user has access to the full command set. You can
-save, commit, branch and merge without ever connecting to a central server.
hunk ./Front\32\Page.page 37
-- **[Smart](Smart Patches)** - **Smart Patches** is what makes darcs stand out
-above the rest. You can cherrypick, merge, apply patches in different orders,
-modify patches and Darcs will know how to do it. With darcs, you can apply patches
-in any order and you will always get the same result.

[Rev #1: Patch Theory Index page.
[email protected]**20090413204930] hunk ./Patch\32\Theory/Index.page 1
-You don't need to know Patch Theory to use darcs. Patch Theory is just for geeks
-who want to know the theory behind darcs amazing Smart Patches. If you just want
-to use darcs, just read [Smart Patches](../Smart Patches).
+You don't need to know Patch Theory to use Darcs. As a user, everything you
+need to know is in the [Patch Reordering](../Patch Reordering) page. That said,
+if you are keen to know more about the theory behind Darcs, we are more than
+happy to tell you all about it.
hunk ./Patch\32\Theory/Index.page 8
-You should read the [Smart Patches](../Smart Patches) page before reading about
-Patch theory. It would help if you also have a little experience using darcs in
-a real project.
+Before you tackle patch theory, you should be familiar with the
+[patch reordering](../Patch Reordering) feature. It would also help if you
+have a little experience kusing Darcs in a real project.
hunk ./Patch\32\Theory/Index.page 15
-- [Examples Revisited]() - A second look at the examples in the [Smart Patches](../Smart Patches) page.
+- [Examples Revisited]() - A second look at the examples in the [Patch Reordering](../Patch Reordering) page.
+- [Answers]() - Answers to exercise problems.

[Rev #1: Patch Theory Answers page.
[email protected]**20090413212451] addfile ./Patch\32\Theory/Answers.page
hunk ./Patch\32\Theory/Answers.page 1
+<table>
+  <tr>
+    <td>Prev:[Examples Revisited]()</td><td>Up:[Index]()</td><td>Next:[]()</td>
+  </tr>
+</table>
+
+This page contains answers to the exercises in the Patch Theory section.
+
+1 Intro
+=======
+
+Exercise 1-1
+------------
+We can prove this just by evaluation:
+<table>
+  <tr>
+    <td>$(AB) (B^{-1}A{-1})$</td><td>$= (AB) (B^{-1}A^{-1})$</td>
+  </tr>
+  <tr>
+    <td></td><td>$= A B B^{-1} A^{-1}$</td>
+  </tr>
+  <tr>
+    <td></td><td>$= A \varepsilon A^{-1}$</td>
+  </tr>
+  <tr>
+    <td></td><td>$= A A^{-1}$</td>
+  </tr>
+  <tr>
+    <td></td><td>$=\varepsilon$</td>
+  </tr>
+</table>
+
+Where $\varepsilon$ denotes the empty patch.
+
+Therefore, $B^{-1}A{-1}$ must be the inverse of $AB$.
+
+Exercise 1-2
+------------
+Let H(X) be a `Hunk` that modifies file X. Let M(X,Y) be the `Move` that
+moves file X to Y. In the following rules X, Y and Z all denote different
+file names:
+
+* `M(X,Y) H(Z) = H(Z) M(X,Y)`
+* `M(X,Y) H(Y) = H(X) M(X,Y)`
+
+And the case `M(X,Y) H(X)` is an error because you cannot edit the old file
+name after the file is reamed.
+
+Exercise 1-3
+------------
+How to write the inverse of a `Hunk`: Given a Hunk patch, you produce its
+inverse just by swapping the `delete` and `add` instructions. For example:
+
+<blockquote>
+<table>
+  <tr>
+    <td>`Foo.txt 42`<br/>`- Daniel likes Bananas.`<br/>`- Daniel likes Mangoes.`<br/>`+ Daniel likes fruits.`</td>
+    <td> -&gt; </td>
+    <td>`Foo.txt 42`<br/>`- Daniel likes fruits.`<br/>`+ Daniel likes Bananas.`<br/>`+ Daniel likes Mangoes.`</td>
+  </tr>
+</table>
+</blockquote>
+

[Rev #1: Patch Reordering page.
[email protected]**20090413213612] move ./Smart\32\Patches.page ./Patch\32\Reordering.page
hunk ./Patch\32\Reordering.page 3
-Smart Patches are coolest feature that darcs has to offer. They are key to
-Darcs' ease of use, easy branching and easy merging.
+**Patch Reorering** is the central feature of darcs. It is the key to its ease
+of use, flexibility and over-all human friendliness.
hunk ./Patch\32\Reordering.page 8
-If you just want to use darcs, this is all you need to know about Smart Patches.
hunk ./Patch\32\Reordering.page 16
-Now you notice that F is an important bugfix that should go into the next stable
-release. But maybe F depends on some stuff you added with D, or with E? Darcs
-can figure out if a patch depends on another, and it can figure out how to
-adapt F to a branch without the other patches.
-
-<center>*Darcs will **always** find the smallest set of patches needed to
-satisfy dependencies.*</center>
-<center>*Darcs does not need to ask you what other patches it needs.*</center>
-<br/>
-Darcs may need to make changes to F to make it fit in the stable branch (e.g.
-change line numbers). We call the new patch F' because it does the
-same thing as F but in the context of a different tree:
+But F is an important bugfix that should go into the next stable release. Darcs
+can figure out if F depends on any changes you made in D or E, and it knows how
+to adapt F to work in a branch with a different set of patches (e.g. Darcs
+might have to change line numbers). We call this modified patch F' because it
+does the same thing as F but in the context of a different tree:
hunk ./Patch\32\Reordering.page 24
-<center>*The idea of transforming patches (e.g. F to F') depending on context<br/>
-is the key idea behind darcs' Smart Patches.*</center>
+Later on, when patches D and E are fully tested, they can be pulled into the
+stable branch. Again, Darcs may need to make adjustments (e.g. change line
+numbers) so we call the new patches D' and E'.
+
+> Stable: A B C F' D' E'
hunk ./Patch\32\Reordering.page 30
+The key feature here is that Darcs knows how to transform a specific patch so
+that it applies to a different tree, allowing you to pick and choose patches
+and to apply patches in any order you like.
+
+A key thing to remember is that **if you apply the same patches in a different
+order you will always get the same result.**
hunk ./Patch\32\Reordering.page 113
-to modify B a little to make it work for Alice. We call the new patch B':
+to modify B to make it work for Alice. We call the new patch B'.
hunk ./Patch\32\Reordering.page 144
-feature of darcs' Smart Patches*</center>
+feature of Patch Reordering*</center>
hunk ./Patch\32\Reordering.page 146
-Darcs' Smart Patches are built upon a solid mathematical foundation called
-[Patch Theory](Patch Theory/Index). But you don't need to know Patch Theory to use
-darcs. You only need to know that darcs will be reliable and predictable.
+Patch Reordering is built on a strong mathematical foundation called
+[Patch Theory](Patch Theory/Index). But you don't need to know Patch Theory to
+use Darcs. You only need to know that Darcs is reliable and predictable.
hunk ./Patch\32\Reordering.page 150
-Example 2: Where other SCMs fear to thread
-==========================================
-This patch-oriented view is unique to darcs. The ability to transform patches
-to apply to a different source tree allows darcs to correctly deal with some
-situations which other SCMs would get wrong. Consider the following example
-using `git` (nothing against Git):
+Example 2: A "complex" merge
+============================
+With most traditional version control systems, a lot of mergers that a human
+would consider quite simple, are made less simple and often even require human
+intervention. Here is one example:
hunk ./Patch\32\Reordering.page 156
-<table>
-  <tr>
-    <th>Git</th><th>Darcs</th><th>Notes</th>
-  </tr>
-<tr>
-<td>
-<blockquote>
-<pre>
-mkdir b1
-cd b1
-git init
-echo 1 > num_file
-git add num_files
-git commit
-cd ..
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-<blockquote>
-<pre>
-mkdir d1
-cd d1
-darcs init
-echo 1 > num_files
-darcs add num_files
-darcs record
-cd ..
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-Create a new project.<br/>
-`num_files` says how many<br/>files exist in the project.
-</td>
-</tr>
-<!-- / / / / / / / / -->
-<tr>
-<td>
-<blockquote>
-<pre>
-git clone b1 b2
-cd b2
-echo 'hi' > foo
-echo 2 > num_files
-git add foo num_files
-git commit
-cd ..
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-<blockquote>
-<pre>
-cp -r d1 d2
-cd d2
-echo 'hi' > foo
-echo 2 > num_files
-darcs add foo
-darcs record
-cd ..
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-Create a new branch.<br/>
-Add file `foo`<br/>
-Update `num_files`<br/>
-</td>
-</tr>
-<!-- / / / / / / / / -->
-<tr>
-<td>
-<blockquote>
-<pre>
-cd b1
-echo 'hi' > bar
-echo 2 > num_files
-git add bar num_files
-git commit
-git pull ../b2
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-<blockquote>
-<pre>
-cd d1
-echo 'hi' > bar
-echo 2 > num_files
-darcs add bar
-darcs record
-darcs pull ../d2
-</pre>
-</blockquote>
-</td> <!-- --> <td>
-Back in the first branch.<br/>
-Add file `bar`<br/>
-Update `num_files`<br/>
-Merge with branch 2.
-</td>
-</tr>
-</table>
+1) Alice creates a new repository which creates a new file called Foo.txt
hunk ./Patch\32\Reordering.page 158
+2) Bob pulls from Alice and he renames Foo.txt to Bar.txt
hunk ./Patch\32\Reordering.page 160
-Git happily merges the branches, creating a broken repository (num_files has the
-value 2 but there are 3 files). On the other hand, Darcs correctly detects the
-potential conflict in having two patches tht make the same change.
+3) Meanwhile, Alice adds content to Foo.txt
hunk ./Patch\32\Reordering.page 162
-Most SCMs would get this wrong because they work by looking at differences
-between branches. The only difference between these branches is the files `foo`
-and `bar`, so the SCM happily merges. Darcs keeps track of individual patches.
-When merging, Darcs tries to apply the same patches to the new branch. This way,
-darcs can see that two patches are making the same change and issue a warning.
+What happens if Bob wants Alice's changes? Sounds straight forward, right? Well,
+in Darcs it *IS*. But in a different VCS (e.g. Mercurial) you have "a branch
+with two heads" and you have to make a specific merge operation, and that
+operation becomes part of the repository's "history". These concepts are not
+intuitive to the human developer. A human simply says "I want feature X".
hunk ./Patch\32\Reordering.page 168
+As you can see, there is a mismatch between how the traditional VCS thinks
+about your work and how you think aobut our work. In contrast, Darcs thinks
+the way you do. You think in terms of "I want feature X" and so does Darcs.
hunk ./Patch\32\Reordering.page 174
-You don't need to know anything else about Smart Patches to use darcs.
-However, if you would like to dig deeper into the theory behind Smart Patches,
-you are welcome to read about [Patch Theory](Patch Theory/Index).
+You don't need to know anything else about Patch Reordering to use darcs.
+However, if you would like to dig deeper into the theory behind Darcs, you are
+invited to read about [Patch Theory](Patch Theory/Index).

[Rev #1: Patch Theory Intro page.
[email protected]**20090413215335] hunk ./Patch\32\Theory/Intro.page 9
-Remember matrices from school?
-==============================
-Did you learn matrix algebra in school? If you liked it, you can think of patch
-theory as being similar to matrix algebra. If you didn't like it, don't read
-this paragraph. :-)
+In this page we introduce the core concepts of Patch Theory. If you learned
+matrix algebra in school and you enjoyed it, it might help you to think of
+patch theory as being similar (but simpler).
hunk ./Patch\32\Theory/Intro.page 77
-**Exercise**: Prove theorem 1.
+**Exercise 1-1**: Prove theorem 1. \[[Answer](Answers#exercise-1-1)\]
hunk ./Patch\32\Theory/Intro.page 135
-**Exercise**: Write down the commutation rules for a Hunk and a Move.
+**Exercise 1-2**: Write down the commutation rules for a Hunk and a Move. \[[Answer](Answers#exercise-1-2)\]
hunk ./Patch\32\Theory/Intro.page 156
-**Exercise**: How would you write the invest of a Hunk?
+**Exercise 1-3**: How would you write the inverse of a Hunk? \[[Answer](Answers#exercise-1-3)\]

[Rev #1: Patch Theory Examples Revisited page.
[email protected]**20090413221617] hunk ./Patch\32\Theory/Examples\32\Revisited.page 5
-    <td>Prev:[Intro]()</td><td>Up:[Index]()</td><td>Next:[]()</td>
+    <td>Prev:[Intro]()</td><td>Up:[Index]()</td><td>Next:[Answers]()</td>
hunk ./Patch\32\Theory/Examples\32\Revisited.page 10
-saw in the [Smart Patches](../Smart Patches) page and figure out why darcs
+saw in the [Patch Reordering](../Patch Reordering) page and figure out why darcs
hunk ./Patch\32\Theory/Examples\32\Revisited.page 17
-introductory page [Smart Patches](../Smart Patches). In this example, we are
+introductory page [Patch Reordering](../Patch Reordering). In this example, we are
hunk ./Patch\32\Theory/Examples\32\Revisited.page 135
-in the page on [Smart Patches](../Smart Patches).
+in the page on [Patch Reordering](../Patch Reordering).
hunk ./Patch\32\Theory/Examples\32\Revisited.page 139
-Example 2 is interesting because we want to figure out, not why a merge suceeds
-but why it it fails. We have two branches, and in each branch we make different
-changes:
+Take a second look at example 2 in the [Patch Reordering](../Patch Reordering)
+page. This time we write the patches explicitly.
hunk ./Patch\32\Theory/Examples\32\Revisited.page 142
+1) Alice creates a new repository (patch X) which creates a new file called Foo.txt
+
+`Alice: X`
+
+2) Bob pulls from Alice and he renames Foo.txt to Bar.txt
+
hunk ./Patch\32\Theory/Examples\32\Revisited.page 150
-    <th colspan="2">Patch A</th><th colspan="2">Patch B</th>
-  </tr>
-  <tr>
-   <td>Patch A1:</td>
-   <td><blockquote><pre>`Add File` bar</pre></blockquote></td>
-   <td>Patch B1:</td>
-   <td><blockquote><pre>`Add File` foo</pre></blockquote></td>
-  </tr>
-  <tr>
-   <td>Patch A2:</td>
-   <td><blockquote><pre>bar 1<br/>+ hi</pre></blockquote></td>
-   <td>Patch B2:</td>
-   <td><blockquote><pre>foo 1<br/>+ hi</pre></blockquote></td>
-  </tr>
-  <tr>
-   <td>Patch A3:</td>
-   <td><blockquote><pre>num_files 1<br/>- 1<br/>+ 2</pre></blockquote></td>
-   <td>Patch B3:</td>
-   <td><blockquote><pre>num_files 1<br/>- 1<br/>+ 2</pre></blockquote></td>
+    <td>`Bob: X B`</td><td> -&gt; </td>
+    <td>`Move Foo.txt Bar.txt`</td>
hunk ./Patch\32\Theory/Examples\32\Revisited.page 155
-We try to appply patch B on top of patch A. (1) Calculate $B^{-1}$,
-(2) Commute $B^{-1}$ and $A$. (3) Use $B^{-1} A = A' B'^{-1}$.
-
-**Calculate** $B^{-1}$ using theorem 1:
-$B^{-1} = (B1 B2 B3)^{-1} = B3^{-1} B2^{-1} B1^{-1}$
+3) Meanwhile, Alice adds content to Foo.txt
hunk ./Patch\32\Theory/Examples\32\Revisited.page 159
-    <th colspan="2">Patch B</th><th colspan="2">Patch $B^{-1}$</th>
-  </tr>
-  <tr>
-   <td>Patch B1:</td>
-   <td><blockquote><pre>`Add File` foo</pre></blockquote></td>
-   <td>Patch $B3^{-1}$:</td>
-   <td><blockquote><pre>num_files 1<br/>- 2<br/>+ 1</pre></blockquote></td>
-  </tr>
-  <tr>
-   <td>Patch B2:</td>
-   <td><blockquote><pre>foo 1<br/>+ hi</pre></blockquote></td>
-   <td>Patch $B2^{-1}$:</td>
-   <td><blockquote><pre>foo 1<br/>- hi</pre></blockquote></td>
-  </tr>
-  <tr>
-   <td>Patch B3:</td>
-   <td><blockquote><pre>num_files 1<br/>- 1<br/>+ 2</pre></blockquote></td>
-   <td>Patch $B1^{-1}$:</td>
-   <td><blockquote><pre>`Remove File` foo</pre></blockquote></td>
+    <td>`Alice: X A`</td><td> -&gt; </td>
+    <td>`Foo.txt 1`<br/>`+ Hello`</td>
hunk ./Patch\32\Theory/Examples\32\Revisited.page 163
+
+The process to merge these is the same as in example 1: (1) Calculate $B^{-1}$,
+(2) Commute $B^{-1}$ and $A$. (3) Use $B^{-1} A = A'B'^{-1}$. To get Alice's
+changes into Bob's tree we just apply $A'$.
+
+<table>
+  <tr><th>Patch $B$</th><th>Patch $B^{-1}$</th><th>Patch $B^{-1}A$</th></tr>
+  <tr>
+    <td>`Move Foo.txt Bar.txt`</td>
+    <td>`Move Bar.txt Foo.txt`</td>
+    <td>`Move Bar.txt Foo.txt`<br/>-----------------<br/>`Foo.txt 1`<br/>`+ Hello`</td>
+  </tr>
+</table>
+
+In exercise 1-2 you learned how to commute a `Move` and a `Hunk`
+[Exercise Answer](Answers#exercise-1-2).
+
+
+<table>
+  <tr><th>$B^{-1}A$</th><th>$A'$$B'^{-1}$</th><th>$A'$</th></tr>
+  <tr>
+    <td>`Move Bar.txt Foo.txt`<br/>-----------------<br/>`Foo.txt 1`<br/>`+ Hello`</td>
+    <td>`Bar.txt 1`<br/>`+ Hello`<br/>-----------------<br/>`Move Bar.txt Foo.txt`</td>
+    <td>`Bar.txt 1`<br/>`+ Hello`</td>
+  </tr>
+</table>
+
+Now we have the $A'$ that Bob's computer needs to apply in order to obtain
+Alice's changes.
hunk ./Patch\32\Theory/Examples\32\Revisited.page 193
-Then we try to commute $B^{-1} A = B3^{-1} B2^{-1} B1^{-1} A1 A2 A3$. We
-quickly run into a problem when we get to the step where we have to commute
-$B3^{-1}$ and $A3$ as they are boht Hunks that affect the same file and the
-same line. Therefore, the commutation fails and so the merge fails.