Understanding Darcs
Total Page:16
File Type:pdf, Size:1020Kb
Understanding Darcs en.wikibooks.org March 15, 2015 On the 28th of April 2012 the contents of the English as well as German Wikibooks and Wikipedia projects were licensed under Creative Commons Attribution-ShareAlike 3.0 Unported license. A URI to this license is given in the list of figures on page 63. If this document is a derived work from the contents of one of these projects and the content was still licensed by the project under this license at the time of derivation this document has to be licensed under the same, a similar or a compatible license, as stated in section 4b of the license. The list of contributors is included in chapter Contributors on page 61. The licenses GPL, LGPL and GFDL are included in chapter Licenses on page 67, since this book and/or parts of it may or may not be licensed under one or more of these licenses, and thus require inclusion of these licenses. The licenses of the figures are given in the list of figures on page 63. This PDF was generated by the LATEX typesetting software. The LATEX source code is included as an attachment (source.7z.txt) in this PDF file. To extract the source from the PDF file, you can use the pdfdetach tool including in the poppler suite, or the http://www. pdflabs.com/tools/pdftk-the-pdf-toolkit/ utility. Some PDF viewers may also let you save the attachment to a file. After extracting it from the PDF file you have to rename it to source.7z. To uncompress the resulting archive we recommend the use of http://www.7-zip.org/. The LATEX source itself was generated by a program written by Dirk Hünniger, which is freely available under an open source license from http://de.wikibooks.org/wiki/Benutzer:Dirk_Huenniger/wb2pdf. Contents 1 Getting Started 3 1.1 Anatomy of a darcs repository ......................... 3 1.2 Essential commands ............................... 4 2 Making Changes 9 2.1 Editing files .................................... 9 2.2 Playing with files ................................. 10 3 Working With Others 13 3.1 The commands .................................. 13 3.2 Dealing with conflicts .............................. 16 4 Reviewing Your Work 17 5 Undoing Mistakes 21 5.1 The big three ................................... 21 5.2 Other ways to get rid of things ......................... 24 5.3 Questions and objections ............................ 25 6 Dealing With Conflicts 27 6.1 Handle your conflicts at home .......................... 27 6.2 Resolving conflicts ................................ 27 7 Introduction to Patch Theory 29 7.1 Math and computer science nerds only ..................... 29 7.2 What is the theory of patches? ......................... 29 7.3 Why all this math? ................................ 29 7.4 Context, patches and changes .......................... 30 7.5 Sequential patches ................................ 32 7.6 Inverses ...................................... 33 7.7 Commutation ................................... 35 7.8 Merging ...................................... 41 7.9 Definitions and properties ............................ 49 8 Intermediary Patch Theory 51 8.1 It’s all patches .................................. 51 8.2 Merging a sequence of patches ......................... 51 8.3 Sequences of patches ............................... 52 8.4 Permutivity .................................... 52 III Contents 9 Patch Theory and Conflicts 53 9.1 Conflicts ...................................... 53 9.2 Forced commutation ............................... 56 9.3 Forced commutation in merging ........................ 56 9.4 Darcs 2 ...................................... 59 9.5 Current research ................................. 59 10 Contributors 61 List of Figures 63 11 Licenses 67 11.1 GNU GENERAL PUBLIC LICENSE ..................... 67 11.2 GNU Free Documentation License ....................... 68 11.3 GNU Lesser General Public License ...................... 69 1 1 Getting Started 1.1 Anatomy of a darcs repository Understanding how to use the darcs commands can be a lot easier if you have a rough idea how things work. We’re not asking you to learn about patch commutation algebra (yet), but one thing you should at least be comfortable with is the anatomy of a darcs repository. Figure 1 Anatomy of a darcs repository The idea of the diagram is as follows: the stuff on the left in yellow is you. That’s what darcs calls the working directory . The stuff in grey, on the other hand, is part of that mysterious _darcs directory if you’ve played around with darcs before. This can be broken down some more. The pristine tree (middle) is exactly like your working directory, except only representing the last saved state. It’s not essential to darcs’s operations, but it makes things run more efficiently, and is perhaps useful for understanding how things work. Finally, the right-most portion is the set of patches . Patches are what makes darcs... well... darcs. Darcs thinks in patches. Almost every darcs operation somehow involves (darcs) juggling some patches around behind the scenes. Enthusiastic darcs users find that this makes life easier in a number of ways. For example, accepting patches to your code 3 Getting Started becomes an extremely natural thing to do - you just let darcs apply them and in they go. But before we get to that, let’s tackle a small set of essential commands. 1.2 Essential commands 1.2.1 init Say you have a directory with some files in it. When you run darcs init to initialise the repository, you get an empty new darcs repository. Your working directory might contain files, but darcs does not know about them yet. Figure 2 After a darcs init - an empty repository 1.2.2 add darcs add tells darcs to keep track of a file or directory that was only in your working directory. It creates or adds to a special temporary patch which we call the pending patch (will be represented in blue). Note that it does not affect your pristine tree whatsover! The 4 Essential commands idea is that we haven’t saved your work (which is what the pristine tree is for). We’ve only told darcs that we might conceivably want to save it later on. Figure 3 during darcs add Note that the pending patch is different from all the other patches. It is really a represen- tation of (some) things you have not yet converted into a real darcs patch. 1.2.3 whatsnew The darcs whatsnew compares the working directory against the pristine tree (theoretically, against the set of patches) and displays what has changed between them. If there is anything in the pending patch, it also displays the contents of that. 5 Getting Started Figure 4 Darcs whatsnew 1.2.4 record The darcs record command is how you save your work. It copies your chosen changes from the working directory to the pristine tree, and more importantly, creates a new patch representing those changes. Changes can also come from the pending patch, and these changes will also be propagated into the pristine tree. 6 Essential commands Figure 5 during darcs record 1 1 http://en.wikibooks.org/wiki/Category%3A 7 2 Making Changes 2.1 Editing files 2.1.1 record makes new stuff old The record command takes the changes which only exist in your working directory (or the pending patch) and updates the pristine tree. The result of a record operation is a new patch. Figure 6 The darcs record command 9 Making Changes 2.1.2 replace for renaming tokens The replace command is useful for explictly telling darcs to replace one word with another (for example, a variable name, if you are a programmer). Note that because of the underlying patch theory, replace only works if the new word doesn’t already exist in the file. Darcs will helpfully let you know if you try to replace something you cannot. Also, there is a switch for forcing the replacement, but the resulting patch is not a clean darcs-replace patch, but a combination of that, and what you would have gotten if you had edited the file in a text editor. In short, forcing darcs to replace when it really doesn’t want to can lead to counter-intuitive results. 2.2 Playing with files We saw add in the last chapter. What about the other file-related commands? 2.2.1 add tells darcs to pay attention add , unsuprisingly, adds a file or directory to the list of files that darcs is paying attention to. 10 Playing with files Figure 7 The darcs add command 2.2.2 mv for moving or renaming mv lets you rename a file or put it in a different directory. This command updates the pending patch with a move command. 2.2.3 you don’t need remove You might think that remove gets rid of a file, but actually all it does is to remove it from the list of files that darcs is paying attention to. You probably just want to delete the file instead (eg: with rm ). Darcs will notice and record the change next time you darcs record that file. So what’s the remove command good for? It might be handy if you want to just remove the file from darcs, without actually getting rid of your physical copy. This is most useful when you’ve accidentally used darcs add on a file you don’t want darcs to pay attention to. 11 Making Changes 1 1 http://en.wikibooks.org/wiki/Category%3A 12 3 Working With Others 3.1 The commands 3.1.1 get darcs get makes a copy of an entire darcs repository. Note that we only get the recorded patches (and pristine tree), not any of the pending stuff. 13 Working With Others Figure 8 during darcs get 3.1.2 pull/push darcs pull copies from some other repository patches that you do not have. The patches are applied to your pristine tree and working directory.