[darcs-users] Patch Theory in action

[Kevin Smith]

I'm trying to figure out patch theory, and specifically at the moment, 
dependencies. I think the patch theory section of the manual would be 
far more understandable if it had concrete examples to augment the 
abstract theories.

So here's an email I sent to a friend/coworker, as I try to grasp the 
simple aspects of how darcs generates and merges patches. Something like 
this might be helpful in a section of the manual for people who want to 
know (basically) what darcs is doing internally.

I would love to hear feedback on this. Hopefully my explanation is 
accurate. Perhaps it is even helpful :-)

There are a couple things I don't understand:

1) How did it figure out that the Change patch depended on the Modify 
patch?

2) As a darcs user, how would I know when I should to manually specify a 
dependency?

Kevin

---
I created an empty repository (repo), and did the following:

echo hello >hello
darcs record
darcs mv hello goodbye
darcs record
echo goodbye >goodbye
darcs record

So now I have a file named goodbye that contains the word goodbye. There 
are three patches in my repository, which I'll call Add, Move, and 
Change. The Change patch appears as a Hunk diff of the file goodbye.

Next, I create a second repo, and 'pull' the Add patch across. Fine. 
Next, I pull the Change patch. darcs first offers me the Move patch, but 
I decline it, and only take the Change patch.

Now, in this second repository, I have still only have a file named 
hello, but now it contains the text 'goodbye'. Very slick. And I think I 
actually understand how it did it.

Here's part of the trick: The Change patch, has the same filename (and 
hash) in both repos. In the first repo, it specifies a change to the 
'goodbye' file. But in the second repo, the patch specifies the 'hello' 
file. Same semantic patch, but different representations based on the 
'context' of the repository it is in. That's patch theory at work.

And that's why you can't include the patch contents (representation) in 
the hash that is used as the unique identifier of that patch. Any patch 
might be 'commuted' to fit its new context.

It's kind of creepy, though. It means that a patch without context is 
meaningless (more or less). If I give you that single patch, without 
giving you access to my repository, it's just a command to modify a 
specific file. It may do what you want, or it may not.

Or, you might receive the same patch from two different people, and it 
might look completely different, but would still "mean" the same thing 
(assuming you had access to the context that each of those patches came 
from).

It's only by knowing that the file on my system used to have a different 
name, and by knowing that both our systems had the original patch that 
created the file in the first place, that it figures out what to do.
---