[darcs-users] how can we improve darcs theory documentation?

AntC anthony_clayden at clear.net.nz
Fri Sep 14 01:58:21 UTC 2012


Eric Kow <kowey <at> darcs.net> writes:

> 
> Hi AntC,
> 
> Thanks for your interest in the Darcs patch theory.
> 
> I was wondering if I could follow up on the discussion by asking for a
> bit of documentation help.

Hi Eric, I sympathise with how hard it is to keep up with documentation. But 
since most of the discussion was new to me, you really don't want me to be the 
one to 'dive in'.

I should say I'm not a serious darcs user, but much more interested in patch 
theory.

> Do you have a few moments to spare to suggest improvements to the
> darcs theory part of the wiki?
> 

The bit I didn't understand until I asked was around duplicates and 
dependencies. I think a series of examples would help:

1. Pull a hunk change.
   This has a dependency on a addfile.
   So discuss how darcs also pulls the addfile.
   And all is well.

2. Pull a hunk change, with dependency on a addfile. [same as 1]
   But the target repo has already pulled the addfile patch.
   So discuss how darcs detects this and ignores the duplicate.
   And all is well.

3. Pull a hunk change, with dependency on a addfile. [same as 1]
   But the target repo already has a file with the same dir/name.
   It was addfile'd direct into the repo.
   Is this OK? Or is this a conflict? (I don't know.)

4. Pull a hunk change, with dependency on a addfile. [same as 1]
   But the target repo has already pulled the addfile patch. [same as 2]
   And then moved/renamed the file.
   Can darcs cope with this?
   (What I hope it does is apply the hunk to the moved file.)

5. Pull a hunk change, with dependency on a addfile. [same as 1]
   But the target repo has already pulled the addfile patch. [same as 2]
   And then removed the file.
   What does darcs do with this? (I don't know.)
   Does darcs pull the addfile again? Or is this a conflict?

6. Pull a hunk change, with dependency on a addfile. [same as 1]
   But the target repo has already pulled the addfile patch. [same as 2]
   And then moved/renamed the file. [same as 4]
   And (worse!) addfile'd direct into the repo with the orig dir/name.
                   [same as 3]
   Can darcs cope with this?
   (What I hope it does is apply the hunk to the moved file.)


> http://darcs.net/Theory
> 

What I didn't see on that page or its links was any mention of duplicate 
patches, and how they're (generally) OK. Owen said duplicates can sometimes 
give rise to conflicts, or get wound up inside other conflicts. I'm not clear 
whether it greatly matters if a conflictor is due to a duplicate or just any 
patch.

> 
> So far:
> 
> - I don't think anybody brought this up but there is also
> http://darcs.net/Theory/Bibliography

Yes I did look there. Most of those references are either very old, or 
incomplete, or musings rather than explanations, or all of that.


AntC



More information about the darcs-users mailing list