Monotone: a Distributed Version Control System
Total Page:16
File Type:pdf, Size:1020Kb
Monotone A distributed version control system Graydon Hoare and others This manual is for the \monotone" distributed version control system. This edition docu- ments version 1.1. Copyright c 2003, 2004, 2011 Graydon Hoare Copyright c 2004, 2005, 2006 Nathaniel Smith Copyright c 2005 - 2010 Derek Scherger Copyright c 2005, 2006 Daniel Carosone Copyright c 2006 Jeronimo Pellegrini Copyright c 2006 Alex Queiroz Copyright c 2006, 2007 William Uther Copyright c 2006 - 2010 Thomas Keller Copyright c 2007 - 2012 Stephen Leake This manual is made available under the GNU GPL version 2.0 or greater. See the accom- panying file COPYING for details. i Table of Contents 1 Concepts :::::::::::::::::::::::::::::::::::::::: 1 1.1 Versions of files :::::::::::::::::::::::::::::::::::::::::::::::: 2 1.2 Versions of trees:::::::::::::::::::::::::::::::::::::::::::::::: 4 1.3 Historical records :::::::::::::::::::::::::::::::::::::::::::::: 6 1.4 Certificates::::::::::::::::::::::::::::::::::::::::::::::::::::: 8 1.5 Storage and workflow ::::::::::::::::::::::::::::::::::::::::: 10 1.6 Forks and merges ::::::::::::::::::::::::::::::::::::::::::::: 13 1.7 Branches:::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 1.7.1 Heads and merging ::::::::::::::::::::::::::::::::::::::: 15 1.7.2 Branch Names ::::::::::::::::::::::::::::::::::::::::::: 17 2 Tutorial :::::::::::::::::::::::::::::::::::::::: 19 2.1 Issues ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 2.1.1 Standard Options :::::::::::::::::::::::::::::::::::::::: 19 2.1.2 Revision Selectors :::::::::::::::::::::::::::::::::::::::: 19 2.2 The Fictional Project ::::::::::::::::::::::::::::::::::::::::: 20 2.3 Creating a Database :::::::::::::::::::::::::::::::::::::::::: 21 2.4 Generating Keys :::::::::::::::::::::::::::::::::::::::::::::: 22 2.5 Starting a New Project:::::::::::::::::::::::::::::::::::::::: 24 2.6 Adding Files :::::::::::::::::::::::::::::::::::::::::::::::::: 25 2.7 Committing Work::::::::::::::::::::::::::::::::::::::::::::: 28 2.8 Basic Network Service::::::::::::::::::::::::::::::::::::::::: 30 2.9 Synchronising Databases :::::::::::::::::::::::::::::::::::::: 31 2.10 Making Changes ::::::::::::::::::::::::::::::::::::::::::::: 32 2.11 Dealing with a Fork :::::::::::::::::::::::::::::::::::::::::: 35 2.12 Branching and Merging :::::::::::::::::::::::::::::::::::::: 38 2.13 Network Service Revisited:::::::::::::::::::::::::::::::::::: 40 3 Advanced Uses :::::::::::::::::::::::::::::::: 45 3.1 Other Transports ::::::::::::::::::::::::::::::::::::::::::::: 46 3.2 Selectors :::::::::::::::::::::::::::::::::::::::::::::::::::::: 47 3.3 Restrictions ::::::::::::::::::::::::::::::::::::::::::::::::::: 52 3.4 Scripting:::::::::::::::::::::::::::::::::::::::::::::::::::::: 54 3.5 Inodeprints ::::::::::::::::::::::::::::::::::::::::::::::::::: 54 3.6 Merge Conflicts ::::::::::::::::::::::::::::::::::::::::::::::: 55 3.6.1 Conflict Types ::::::::::::::::::::::::::::::::::::::::::: 55 3.7 Workspace Collisions :::::::::::::::::::::::::::::::::::::::::: 61 3.8 Quality Assurance :::::::::::::::::::::::::::::::::::::::::::: 63 3.9 Vars :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 64 3.10 Managed Databases :::::::::::::::::::::::::::::::::::::::::: 65 3.11 Reserved Files ::::::::::::::::::::::::::::::::::::::::::::::: 67 3.12 Reserved Certs::::::::::::::::::::::::::::::::::::::::::::::: 69 ii monotone documentation 3.13 Naming Conventions ::::::::::::::::::::::::::::::::::::::::: 71 3.14 File Attributes ::::::::::::::::::::::::::::::::::::::::::::::: 72 3.15 Migrating and Dumping:::::::::::::::::::::::::::::::::::::: 73 3.16 Importing from CVS ::::::::::::::::::::::::::::::::::::::::: 74 3.17 Exporting to GIT :::::::::::::::::::::::::::::::::::::::::::: 75 3.18 Using packets :::::::::::::::::::::::::::::::::::::::::::::::: 77 3.19 Bisecting :::::::::::::::::::::::::::::::::::::::::::::::::::: 80 4 Command Reference :::::::::::::::::::::::::: 81 4.1 Global and Common Options:::::::::::::::::::::::::::::::::: 82 4.1.1 Global Options::::::::::::::::::::::::::::::::::::::::::: 82 4.1.2 Common Options :::::::::::::::::::::::::::::::::::::::: 84 4.2 Tree :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 85 4.2.1 Conflicts ::::::::::::::::::::::::::::::::::::::::::::::::: 89 4.3 Workspace :::::::::::::::::::::::::::::::::::::::::::::::::::: 91 4.4 Network :::::::::::::::::::::::::::::::::::::::::::::::::::::: 97 4.5 Informative :::::::::::::::::::::::::::::::::::::::::::::::::: 100 4.6 Review :::::::::::::::::::::::::::::::::::::::::::::::::::::: 108 4.7 Variables :::::::::::::::::::::::::::::::::::::::::::::::::::: 109 4.8 Key and Cert :::::::::::::::::::::::::::::::::::::::::::::::: 111 4.9 Packet I/O :::::::::::::::::::::::::::::::::::::::::::::::::: 113 4.10 Database ::::::::::::::::::::::::::::::::::::::::::::::::::: 114 4.11 Automation :::::::::::::::::::::::::::::::::::::::::::::::: 119 4.12 VCS :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 180 5 Formats ::::::::::::::::::::::::::::::::::::::: 183 5.1 basic_io Format :::::::::::::::::::::::::::::::::::::::::::: 183 6 Lua Reference :::::::::::::::::::::::::::::::: 185 6.1 Hooks ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 186 6.1.1 Common Data Types ::::::::::::::::::::::::::::::::::: 186 6.1.2 Event Notifications and Triggers::::::::::::::::::::::::: 186 6.1.3 User Defaults ::::::::::::::::::::::::::::::::::::::::::: 189 6.1.4 Netsync Permission Hooks :::::::::::::::::::::::::::::: 193 6.1.5 Netsync Transport Hooks ::::::::::::::::::::::::::::::: 195 6.1.6 Trust Evaluation Hooks ::::::::::::::::::::::::::::::::: 197 6.1.7 External Diff Tools:::::::::::::::::::::::::::::::::::::: 198 6.1.8 External Merge Tools ::::::::::::::::::::::::::::::::::: 199 6.1.9 Selector Expansion :::::::::::::::::::::::::::::::::::::: 200 6.1.10 Attribute Handling::::::::::::::::::::::::::::::::::::: 201 6.1.11 GIT Export Hooks ::::::::::::::::::::::::::::::::::::: 202 6.1.12 Validation Hooks::::::::::::::::::::::::::::::::::::::: 203 6.2 Additional Lua Functions :::::::::::::::::::::::::::::::::::: 204 6.3 Implementation Differences :::::::::::::::::::::::::::::::::: 208 iii 7 Special Topics :::::::::::::::::::::::::::::::: 209 7.1 Internationalization :::::::::::::::::::::::::::::::::::::::::: 210 7.2 Hash Integrity ::::::::::::::::::::::::::::::::::::::::::::::: 213 7.3 Rebuilding ancestry :::::::::::::::::::::::::::::::::::::::::: 216 7.4 Regular Expression Syntax ::::::::::::::::::::::::::::::::::: 218 7.4.1 Regexp Syntax Summary:::::::::::::::::::::::::::::::: 218 7.4.2 Regexp Details :::::::::::::::::::::::::::::::::::::::::: 225 Appendix A Default hooks:::::::::::::::::::: 255 General Index :::::::::::::::::::::::::::::::::::: 289 Chapter 1: Concepts 1 1 Concepts This chapter should familiarize you with the concepts, terminology, and behavior described in the remainder of the user manual. Please take a moment to read it, as later sections will assume familiarity with these terms. 2 monotone documentation 1.1 Versions of files Suppose you wish to modify a file file.txt on your computer. You begin with one version of the file, load it into an editor, make some changes, and save the file again. Doingso produces a new version of the file. We will say that the older version of the file wasa parent, and the new version is a child, and that you have performed an edit between the parent and the child. We may draw the relationship between parent and child using a graph, where the arrow in the graph indicates the direction of the edit, from parent to child. file.txt parent version file.txt child version We may want to identify the parent and the child precisely, for sake of reference. To do so, we will compute a cryptographic hash function, called sha1, of each version. The details of this function are beyond the scope of this document; in summary, the sha1 function takes a version of a file and produces a short string of 20 bytes, which we will use touniquely identify the version1. Now our graph does not refer to some \abstract" parent and child, but rather to the exact edit we performed between a specific parent and a specific child. file.txt SHA1 65f1bde1f38262034e7c3457301e8f736ba6381b parent version file.txt SHA1 a91566316d208dc405795904f8d67ae3a0e765cb child version When dealing with versions of files, we will dispense with writing out “file names", and identify versions purely by their sha1 value, which we will also refer to as their file ID. Using IDs alone will often help us accommodate the fact that people often wish to call files 1 We say sha1 values are \unique" here, when in fact there is a small probability of two different versions having the same sha1 value. This probability is very small, so we discount it. Chapter 1: Concepts 3 by different names. So now our graph of parent and child is just a relationship betweentwo versions, only identified by ID. 65f1bde1f38262034e7c3457301e8f736ba6381b parent version a91566316d208dc405795904f8d67ae3a0e765cb child version Version control systems, such as monotone, are principally concerned with the storage and management of multiple versions of some files. One way to store multiple versions ofa file is, literally, to save a separate complete copy of the file, every time you make a change. When necessary, monotone will save complete copies of your files, compressed with the zlib compression format. Hello there Hello Hello, World! world, how do you do? 1st version 2nd version 3rd version Often we find that successive versions of a file are