← Back to branch summary

~svn/ubuntu/oneiric/subversion/ppa

« back to all changes in this revision

Viewing changes to notes/fs_dumprestore.txt

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-12-05 01:26:14 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051205012614-qom4xfypgtsqc2xq
Tags: 1.2.3dfsg1-3ubuntu1
Merge with the final Debian release of 1.2.3dfsg1-3, bringing in
fixes to the clean target, better documentation of the libdb4.3
upgrade and build fixes to work with swig1.3_1.3.27.

Show diffs side-by-side

added added

removed removed

Lines of Context:
notes/fs_dumprestore.txt
 
1
 
 
2
A proposal for an svn filesystem dump/restore format.
 
3
 
 
4
Two problems we want to solve
 
5
=============================
 
6
 
 
7
 1.  When we change our node-id schema, we need to migrate all of our
 
8
     data (by dumping and restoring).
 
9
 
 
10
 2.  Serves as a backup format.  Could be read by other software tools
 
11
     someday.
 
12
 
 
13
 
 
14
Design Goals
 
15
============
 
16
 
 
17
 A.  Written as two new public functions in svn_fs.h.  To be invoked
 
18
     by new 'svnadmin' subcommands.
 
19
 
 
20
 B.  Format uses only timeless fs concepts.
 
21
 
 
22
     The dump format needs to reference concepts that we *know* are
 
23
     general enough to never change.  These concepts must exist
 
24
     independently of any internal node-id schema, or any DB storage
 
25
     backend.  In other words, we're talking about the basic ideas in
 
26
     our original "design spec" from May 2000.
 
27
 
 
28
 
 
29
Format Semantics
 
30
================
 
31
 
 
32
Here are the timeless semantics of our fs design -- the things that
 
33
would be stored in our dump format.
 
34
 
 
35
  - A filesystem is an array of trees.
 
36
    Each tree is called a "revision" and has unversioned properties attached.
 
37
 
 
38
  - A revision has a tree of "nodes" hanging off of it.
 
39
    Actually, the nodes in the filesystem form a DAG.  A revision
 
40
    always points to an initial node that represents the 'root' of some tree.
 
41
 
 
42
  - The majority of a tree's nodes are hard-links (references) to
 
43
    nodes that were created in earlier trees.
 
44
 
 
45
  - A node contains 
 
46
 
 
47
        - versioned text
 
48
        - versioned properties
 
49
        - predecessor history:  "which node am I a variant of?"
 
50
        - copy history:  "which node am I a copy of?"
 
51
 
 
52
    The history values can be non-existent (meaning the node is
 
53
    completely new), or can have a value of {revision, path}.
 
54
 
 
55
 
 
56
------------------------------------------------------------------------
 
57
Refinement of proposal #2:  (after discussion with gstein)
 
58
=========================
 
59
 
 
60
Each node starts with RFC822-style headers at the top.  The final
 
61
header is a 'Content-length:', followed by the content, so record
 
62
boundaries can be inferred.
 
63
 
 
64
The content section has two implicit parts: a property hash, and the
 
65
fulltext.  The division between these two sections is implied by the
 
66
"PROPS-END\n" tag at the end of the prophash.  In the case of a
 
67
directory node or a revision, only the prophash is present.
 
68
 
 
69
-----------------------------------------------------------------
 
70
 
 
71
SVN DUMPFILE VERSION 1 FORMAT
 
72
 
 
73
The format starts with the version number of the dump format
 
74
("SVN-fs-dump-format-version: 1\n"), followed by a series of revision
 
75
records.  Each revision record starts with information about the
 
76
revision, followed by a variable number of node changes for that
 
77
revision.  Fields in [braces] are optional, and unknown headers are
 
78
always ignored, for backwards compatibility.
 
79
 
 
80
Revision-number: N
 
81
Prop-content-length: P
 
82
Content-length: L
 
83
 
 
84
   ...P bytes of property data.  Properties are stored in the same
 
85
   human-readable hashdump format used by working copy property files,
 
86
   except that they end with "PROPS-END\n" for better readability.
 
87
 
 
88
Node-path: /absolute/path/to/node/in/filesystem
 
89
Node-kind: file | dir  (1)
 
90
Node-action: change | add | delete | replace
 
91
[Node-copyfrom-rev: X]
 
92
[Node-copyfrom-path: /path ]
 
93
[Text-copy-source-md5: blob] (2)
 
94
[Text-content-md5: blob]
 
95
[Text-content-length: T]
 
96
[Prop-content-length: P]
 
97
Content-length: Y (3)
 
98
 
 
99
   ... Y bytes of content data, divided into P bytes of "property"
 
100
   data and T bytes of "text" data.  The properties come first; their
 
101
   total length (including formatting) is Prop-content-length, and is
 
102
   included in Node-content-length.  The "PROPS-END\n" line always
 
103
   terminates the property section if there are props.  The remainder
 
104
   of the Y bytes (expected to be equivalent to Text-content-length)
 
105
   represent the contents of the node.
 
106
 
 
107
 
 
108
Notes:
 
109
 
 
110
(1) if the node represents a deletion, this field is optional.
 
111
 
 
112
(2) this is a checksum of the source of the copy.  a loader process
 
113
    can use this checksum to determine that the copyfrom path/rev
 
114
    already present in a filesystem is really the *correct* one to use.
 
115
 
 
116
(3) the Content-length header is technically unnecessary, since the
 
117
    information it holds (and more) can be found in the
 
118
    Prop-content-length and Text-content-length fields.  Though
 
119
    Subversion itself does not make use of the header when reading a
 
120
    dumpfile, we include it for compatibility with generic RFC822
 
121
    parsers.
 
122
 
 
123
(4) There are actually 2 types of version 1 dump streams. The regular ones
 
124
    are generated since r2634 (svn 0.14.0). Older ones also claim to be
 
125
    version 1, but miss the Props-content-length and Text-content-length
 
126
    fields in the block header. In those days there *always* was a
 
127
    properties block.
 
128
 
 
129
-----------------------------------------------------------------
 
130
EXAMPLE
 
131
 
 
132
Here's an example of revision 1422, whereby I added a new directory
 
133
"baz", added a new file "bop" inside it, and modified the file "foo.c":
 
134
 
 
135
 
 
136
Revision-number: 1422
 
137
Prop-content-length: 80
 
138
Content-length: 80
 
139
 
 
140
K 6
 
141
author
 
142
V 7
 
143
sussman
 
144
K 3
 
145
log
 
146
V 17
 
147
Added two files, changed a third.
 
148
PROPS-END
 
149
 
 
150
Node-path: bar/baz
 
151
Node-kind: dir
 
152
Node-action: add
 
153
Prop-content-length: 35
 
154
Content-length: 35
 
155
 
 
156
K 10
 
157
svn:ignore
 
158
V 4
 
159
TAGS
 
160
PROPS-END
 
161
 
 
162
 
 
163
Node-path: bar/baz/bop
 
164
Node-kind: file
 
165
Node-action: add
 
166
Prop-content-length: 76
 
167
Text-content-length: 54
 
168
Content-length: 130
 
169
 
 
170
K 14
 
171
svn:executable
 
172
V 2
 
173
on
 
174
K 12
 
175
svn:keywords
 
176
V 15
 
177
LastChangedDate
 
178
PROPS-END
 
179
Here is the text of the newly added 'bop' file.
 
180
Whee.
 
181
 
 
182
Node-path: bar/foo.c
 
183
Node-kind: file
 
184
Node-action: change
 
185
Text-content-length: 102
 
186
Content-length: 102
 
187
 
 
188
Here is the fulltext of my change to an existing /bar/foo.c.
 
189
Notice that this file has no properties.
 
190
 
 
191
-------------------------------------
 
192
 
 
193
SVN DUMPFILE VERSION 2 FORMAT
 
194
 
 
195
This format is equivalent to the VERSION 1 format in every respect,
 
196
except for the following:
 
197
 
 
198
1.) The format starts with the new version number of the dump format
 
199
    ("SVN-fs-dump-format-version: 2\n").
 
200
 
 
201
2.) In addition to "Revision Records", another sort of record is supported:
 
202
    the "UUID" record, which should be of the form:
 
203
 
 
204
UUID: 7bf7a5ef-cabf-0310-b7d4-93df341afa7e
 
205
 
 
206
    This should be used to indicate the UUID of the originating repository.
 
207
 
 
208
-------------------------------------
 
209
 
 
210
SVN DUMPFILE VERSION 3 FORMAT
 
211
 
 
212
This format is equivalent to the VERSION 2 format except for the
 
213
following:
 
214
 
 
215
1.) The format starts with the new version number of the dump format
 
216
    ("SVN-fs-dump-format-version: 3\n").
 
217
 
 
218
2.) There are two new optional headers for node changes:
 
219
 
 
220
[Text-delta: true|false]
 
221
[Prop-delta: true|false]
 
222
 
 
223
    The default value for these headers is "false".  If the value is
 
224
    set to "true", then the text and property contents will be treated
 
225
    as deltas against the previous contents of the node (as determined
 
226
    by copy history for adds with history, or by the value in the
 
227
    previous revision for changes--just as with commits).
 
228
 
 
229
Property deltas have the same format as regular property lists except
 
230
that (1) properties with the same value as in the previous contents of
 
231
the node are not printed, and (2) deleted properties will be written
 
232
out as
 
233
 
 
234
D <name length>
 
235
<name>
 
236
 
 
237
just as a regular property is printed, but with the "K " changed to a
 
238
"D " and with no value part.
 
239
 
 
240
Text deltas are written out as a series of svndiff windows.