← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/revfile.txt

  • Committer: Martin Pool
  • Date: 2005-05-02 07:20:35 UTC
  • Revision ID: mbp@sourcefrog.net-20050502072035-e9467e0d64e81cdc
doc: revfile storage and related things

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/revfile.txt
 
1
********
 
2
Revfiles
 
3
********
 
4
 
 
5
The unit for compressed storage in bzr is a *revfile*, whose design
 
6
was suggested by Matt Mackall.
 
7
 
 
8
 
 
9
Requirements
 
10
============
 
11
 
 
12
Compressed storage is a tradeoff between several goals:
 
13
 
 
14
* Reasonably compact storage of long histories.
 
15
 
 
16
* Robustness and simplicity.
 
17
 
 
18
* Fast extraction of versions and addition of new versions (preferably
 
19
  without rewriting the whole file, or reading the whole history.)
 
20
 
 
21
* Fast and precise annotations.
 
22
 
 
23
* Storage of files of at least a few hundred MB.
 
24
 
 
25
 
 
26
Design
 
27
======
 
28
 
 
29
revfiles store the history of a single logical file, which is
 
30
identified in bzr by its file-id.  In this sense they are similar to
 
31
an RCS or CVS ``,v`` file or an SCCS sfile.
 
32
 
 
33
Each state of the file is called a *text*. 
 
34
 
 
35
Renaming, adding and deleting this file is handled at a higher level
 
36
by the inventory system, and is outside the scope of the revfile.  The
 
37
revfile name is typically based on the file id which is itself
 
38
typically based on the name the file had when it was first added.  But
 
39
this is purely cosmetic.
 
40
 
 
41
    For example a file now called ``frob.c`` may have the id
 
42
    ``frobber.c-12873`` because it was originally called
 
43
    ``frobber.c``.  Its texts are kept in the revfile
 
44
    ``.bzr/revfiles/frobber.c-12873.revs``.
 
45
 
 
46
When the file is deleted from the inventory the revfile does not
 
47
change.  It's just not used in reproducing trees from that point
 
48
onwards.
 
49
 
 
50
The revfile does not record the date when the text was added, a commit
 
51
message, properties, or any other metadata.  That is handled in the
 
52
higher-level revision history.
 
53
 
 
54
Inventories and other metadata files that vary from one version to the
 
55
next can themselves be stored in revfiles.
 
56
 
 
57
revfiles store files as simple byte streams, with no consideration of
 
58
translating character sets, line endings, or keywords.  Those are also
 
59
handled at a higher level.  However, the revfile may make use of
 
60
knowledge that a file is line-based in generating a diff.  
 
61
 
 
62
   (The Python builtin difflib is too slow when generating a purely
 
63
   byte-by-byte delta so we always make a line-by-line diff; when this
 
64
   is fixed it may be feasible to use line-by-line diffs for all
 
65
   files.)
 
66
 
 
67
Files whose text does not change from one revision to the next are
 
68
stored as just a single text in the revfile.  This can happen even if
 
69
the file was renamed or other properties were changed in the
 
70
inventory. 
 
71
 
 
72
 
 
73
Skip-deltas
 
74
-----------
 
75
 
 
76
Because the basis of a delta does not need to be the text's logical
 
77
predecessor, we can adjust the deltas 
 
78
 
 
79
 
 
80
Annotations
 
81
-----------
 
82
 
 
83
Storing
 
84
 
 
85
 
 
86
Open issues
 
87
===========
 
88
 
 
89
* revfiles use unsigned 32-bit integers both in diffs and the index.
 
90
  This should be more than enough for any reasonable source file but
 
91
  perhaps not enough for large binaries that are frequently committed.
 
92
 
 
93
  Perhaps for those files there should be an option to continue to use
 
94
  the text-store.  There is unlikely to be any benefit in holding
 
95
  deltas between them, and deltas will anyhow be hard to calculate. 
 
96
 
 
97
* The append-only design does not allow for destroying committed data,
 
98
  as when confidential information is accidentally added.  That could
 
99
  be fixed by creating the fixed repository as a separate branch, into
 
100
  which only the preserved revisions are exported.