monotone

monotone Mtn Source Tree

Root/README.changesets

1Information about the changeset branch integration
2==================================================
3
4Between versions 0.14 and 0.15 monotone underwent a major
5reorganization of its fundamental data structures. This means pre-0.14
6and post-0.15 versions of monotone are strictly incompatible:
7
8 - databases are incompatible
9 - network service is incompatible
10
11Unfortunately we were simply not able to make transparent
12interoperation possible. Too much changed. However, it is possible to
13*migrate* from the pre-0.14 representation to the post-0.15
14representation. The migration is slightly lossy, but it is the best we
15are able to provide.
16
17
18What changed
19============
20
21The change added two new objects to the vocabulary of monotone:
22
23 - changesets
24 - revisions
25
26They are both text objects, like manifests, which monotone reads and
27writes for its own benefit. Revisions are, like manifests, also hashed
28with SHA1 to produce revision IDs. Changesets are not hashed, because
29they generally do not appear outside of revisions.
30
31These two new objects replace three previous objects: patch sets,
32rename certs, and ancestry certs. Now information about renaming and
33patch application is stored in changesets, and information about
34ancestry is stored in revisions. Obviously these objects store the
35information slightly differently than their predecessors. See the next
36section for motivation.
37
38The observable affect for the end user is moderate: most monotone
39commands work "the way they used to", except that now they take
40revision IDs where they used to take manifest IDs. Don't worry about
41this too much: every revision has a reference to a specific manifest
42as well, revision IDs still always refer to a specific "tree state",
43they just happen to refer to a bit *more* than that as well, as we'll
44see.
45
46
47Why it changed
48==============
49
50The old objects were buggy. There were a bunch of subtle and
51difficult-to-fix problems with the way we were representing ancestry
52and renames before:
53
54 - renames of directories had to be inferred, and this could fail.
55
56 - nontrivial forms of rename chaining didn't work, and it wasn't clear
57 that they could be made to work treating renames as we did:
58 a->b and b->a
59 a->b and c->a
60 a/b->a/c and a->d (depending on order)
61
62 - you could have multiple *irreconcilable* rename certs attached
63 to the same manifest edge, and this would cause monotone to crash.
64
65 - ancestry could form cycles, if you ever returned to a previous
66 manifest state.
67
68 - ancestry could accidentally jump from one "historical thread" to
69 another if you happened to pass through the same manifest state;
70 two branches acquiring the same state would always look like a
71 merge even when it was a coincidence.
72
73 - it wasn't clear what monotone should do if you assigned different
74 trust to existant branch, ancestry, and rename certs.
75
76These problems were with us for quite a while, even if you didn't
77encounter them. The changes at 0.15 fix the whole family of bugs by
78removing the troubling abstractions and replacing them with more
79robust ones. In particular:
80
81 - Unlike ancestry certs, revisions are chained. Each revision
82 contains *as part of its content* the revision IDs of its
83 predecessor revisions, so there can never be a loop in the
84 graph. Each new point in the graph gets a new, previously-unseen
85 ID.
86
87 - Revisions are not subject to trust evaluation, they are
88 *statements of fact*. They happen to be stating a fact which
89 describes an entire historical chain of events, but there is only
90 one trust evaluation: branch membership. The evaluation of branch
91 membership covers the entire history of events described by a
92 revision.
93
94 - Changesets have much stronger reasoning facilities about
95 overlapping renames, directory renames, etc. They actually break
96 down into a "simultaneous rearrangement of inodes" abstraction, in
97 memory, including directories as first class objects. This
98 abstraction has a clear algebra for concatenation, inversion and
99 parallel merger.
100
101
102How do I migrate?
103=================
104
105Before you start any of this, make a backup of the database. All the
106world's warnings about making backups seem to go un-heeded, but
107seriously, it's just a single "cp" command. How lazy can you get?
108
109 $ cp mydatabase.db mydatabase.db.pre-changesets
110
111Please be sure to do so. After backing up, there are three required
112steps (and one optional step) to the migration. The first step is to
113dump and reload your database, to get something that the new version
114of SQLite can read. Note that you need to keep your old version of
115monotone around at least long enough to perform this step:
116
117 $ old-monotone --db=mydatabase.db db dump > mydatabase.dump
118 $ monotone --db=new-mydatabase.db db load < mydatabase.dump
119
120The next step is the usual "thing you do when the SQL schema changes":
121
122 $ monotone --db=new-mydatabase.db db migrate
123
124Then there is the new step: telling monotone to convert its old
125representation of manifests to changesets. It will synthesize a lot of
126new changesets based on what it can find in your database. The newly
127synthesized information is a *slightly lossy* version of the
128information already found in your database. It is lossy in the
129following respects:
130
131 - All existing rename/edit events will be degraded to delete/add
132 events
133
134 - All existing manifest certs will be reissued as revision certs,
135 but signed *with your public key*. All previous RSA-key-identity
136 information is thereby lost.
137
138Assuming you're prepared to live with this loss, the next step is to run
139a special, otherwise undocumented "changesetification" command:
140
141 $ monotone --db=new-mydatabase.db db changesetify
142
143This should build the new changeset and revision structure and issue
144all the necessary certs. It will therefore take a while on a large
145database. It will not, however, delete the old manifest certs: the new
146version of monotone will simply ignore them, but they continue to
147exist in your database, should you wish to recover some of their
148information for forensic purposes in the future. If you truly wish to
149remove all manifest certs as well (they are all subsumed by revision
150certs now, anyways) you can issue one further command:
151
152 $ monotone --db=new-mydatabase.db db execute "delete from manifest_certs"
153
154This will purge the manifest_certs table of all its entries, but as we
155said this step is purely optional. No harm will come from old manifest
156certs remaining in your database.

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status