← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/knitpack.txt

  • Committer: Martin Pool
  • Date: 2007-10-24 02:33:14 UTC
  • mto: This revision was merged to the branch mainline in revision 2933.
  • Revision ID: mbp@sourcefrog.net-20071024023314-l9mscm8wsb1bvj1f
typo

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/knitpack.txt
1
 
==========================
2
1
KnitPack repository format
3
2
==========================
4
3
 
5
 
.. contents::
6
 
 
7
 
Using KnitPack repositories
8
 
===========================
9
 
 
10
 
Motivation
11
 
----------
12
 
 
13
 
KnitPack is a new repository format for Bazaar, which is expected to be
14
 
faster both locally and over the network, is usually more compact, and
15
 
will work with more FTP servers.
16
 
 
17
 
Our benchmarking results to date have been very promising. We fully expect
18
 
to make a pack-based format the default in the near future.  We would
19
 
therefore like as many people as possible using KnitPack repositories,
20
 
benchmarking the results and telling us where improvements are still needed.
21
 
 
22
 
Preparation
23
 
-----------
24
 
 
25
 
A small percentage of existing repositories may have some inconsistent
26
 
data within them. It's is a good idea to check the integrity of your
27
 
repositories before migrating them to knitpack format. To do this, run::
28
 
 
29
 
  bzr check
30
 
 
31
 
If that reports a problem, run this command::
32
 
 
33
 
  bzr reconcile
34
 
 
35
 
Note that this can take many hours for repositories with deep history
36
 
so be sure to set aside some time for this if it is required.
37
 
 
38
 
Creating a new knitpack branch
39
 
------------------------------
40
 
 
41
 
If you're starting a project from scratch, it's easy to make it a
42
 
``knitpack`` one. Here's how::
43
 
 
44
 
  cd my-stuff
45
 
  bzr init --pack-0.92
46
 
  bzr add
47
 
  bzr commit -m "initial import"
48
 
 
49
 
In other words, use the normal sequence of commands but add the
50
 
``--pack-0.92`` option to the ``init`` command.
51
 
 
52
 
**Note:** In bzr 0.92, this format was called ``knitpack-experimental``.
53
 
 
54
 
Creating a new knitpack repository
55
 
----------------------------------
56
 
 
57
 
If you're starting a project from scratch and wish to use a shared repository
58
 
for branches, you can make it a ``knitpack`` repository like this::
59
 
 
60
 
  cd my-repo
61
 
  bzr init-repo --pack-0.92 .
62
 
  cd my-stuff
63
 
  bzr init
64
 
  bzr add
65
 
  bzr commit -m "initial import"
66
 
 
67
 
In other words, use the normal sequence of commands but add the
68
 
``--pack-0.92`` option to the ``init-repo`` command.
69
 
 
70
 
Upgrading an existing branch or repository to knitpack format
71
 
-------------------------------------------------------------
72
 
 
73
 
If you have an existing branch and wish to migrate it to
74
 
a ``knitpack`` format, use the ``upgrade`` command like this::
75
 
 
76
 
  bzr upgrade --pack-0.92 path-to-my-branch
77
 
 
78
 
If you are using a shared repository, run::
79
 
 
80
 
  bzr upgrade --pack-0.92 ROOT_OF_REPOSITORY
81
 
 
82
 
to upgrade the history database. Note that this will not
83
 
alter the branch format of each branch, so
84
 
you will need to also upgrade each branch individually
85
 
if you are upgrading from an old (e.g. < 0.17) bzr.
86
 
More modern bzr's will already have the branch format at
87
 
our latest branch format which adds support for tags.
88
 
 
89
 
Starting a new knitpack branch from one in an older format
90
 
----------------------------------------------------------
91
 
 
92
 
This can be done in one of several ways:
93
 
 
94
 
1. Create a new branch and pull into it
95
 
2. Create a standalone branch and upgrade its format
96
 
3. Create a knitpack shared repository and branch into it
97
 
 
98
 
Here are the commands for using the ``pull`` approach::
99
 
 
100
 
    bzr init --pack-0.92 my-new-branch
101
 
    cd my-new-branch
102
 
    bzr pull my-source-branch
103
 
 
104
 
Here are the commands for using the ``upgrade`` approach::
105
 
 
106
 
    bzr branch my-source-branch my-new-branch
107
 
    cd my-new-branch
108
 
    bzr upgrade --pack-0.92 .
109
 
 
110
 
Here are the commands for the shared repository approach::
111
 
 
112
 
  cd my-repo
113
 
  bzr init-repo --pack-0.92 .
114
 
  bzr branch my-source-branch my-new-branch
115
 
  cd my-new-branch
116
 
 
117
 
As a reminder, any of the above approaches can fail if the source branch
118
 
has inconsistent data within it and hasn't been reconciled yet. Please
119
 
be sure to check that before reporting problems.
120
 
 
121
 
Testing packs for bzr-svn users
122
 
-------------------------------
123
 
 
124
 
If you are using ``bzr-svn`` or are testing the prototype subtree support,
125
 
you can still use and assist in testing KnitPacks. The commands to use
126
 
are identical to the ones given above except that the name of the format
127
 
to use is ``knitpack-subtree-experimental``.
128
 
 
129
 
WARNING: Note that the subtree formats, ``dirstate-subtree`` and
130
 
``knitpack-subtree-experimental``, are **not** production strength yet and
131
 
may cause unexpected problems. They are required for the bzr-svn
132
 
plug-in but should otherwise only be used by people happy to live on the
133
 
bleeding edge. If you are using bzr-svn, you're on the bleeding edge anyway.
134
 
:-)
135
 
 
136
 
Reporting problems
137
 
------------------
138
 
 
139
 
If you need any help or encounter any problems, please contact the developers
140
 
via the usual ways, i.e. chat to us on IRC or send a message to our mailing
141
 
list. See http://bazaar-vcs.org/BzrSupport for contact details.
142
 
 
143
 
 
144
 
Technical notes
145
 
===============
146
 
 
147
4
Bazaar 0.92 adds a new format (experimental at first) implemented in
148
 
``bzrlib.repofmt.pack_repo.py``.
 
5
``bzrlib.repofmt.pack_repo.py``.  
149
6
 
150
7
This format provides a knit-like interface which is quite compatible
151
8
with knit format repositories: you can get a VersionedFile for a
158
15
==================== =============================================
159
16
packs/               completed readonly packs
160
17
indices/             indices for completed packs
161
 
upload/              temporary files for packs currently being
 
18
upload/              temporary files for packs currently being 
162
19
                     written
163
 
obsolete_packs/      packs that have been repacked and are no
 
20
obsolete_packs/      packs that have been repacked and are no 
164
21
                     longer normally needed
165
22
pack-names           index of all live packs
166
23
lock/                lockdir
186
43
                                             compression base
187
44
======== ========== ======================== ==========================
188
45
 
189
 
Indices are accessed through the ``bzrlib.index.GraphIndex`` class.
 
46
Indices are accessed through the ``bzrlib.index.GraphIndex`` class.  
190
47
Indices are stored as sorted files on disk.  Each line is one record,
191
48
and contains:
192
49
 
193
50
 * key fields
194
51
 * a value string - for all these indices, this is an ascii decimal pair
195
 
   of "offset length" giving the position of the referenced data within
 
52
   of "offset length" giving the position of the refenced data within 
196
53
   the pack body file
197
54
 * a list of zero or more reference lists
198
55
 
221
78
 
222
79
It is not possible to regenerate an index from the body file, because it
223
80
contains information stored in the knit index that's not in the body.
224
 
(In particular, the per-file graph is only stored in the index.)
 
81
(In particular, the per-file graph is only stored in the index.) 
225
82
We would like to change this in a future format.
226
83
 
227
84
The lock is a regular LockDir lock.  The lock is only held for a much
229
86
insertion can be done without the repository locked.  This is an
230
87
implementation detail; the repository user should still call
231
88
``repository.lock_write`` at the regular time but be aware this does not
232
 
correspond to a physical mutex.
 
89
correspond to a physical mutex. 
233
90
 
234
91
Read locks control caching but do not affect writers.
235
92
 
236
93
The newly-added repository write group concept is very important to
237
94
KnitPack repositories.  When ``start_write_group`` is called, a new
238
 
temporary pack is created and all modifications to the repository will
 
95
temporary pack is created and all modifications to the repository will 
239
96
go into it until either ``commit_write_group`` or ``abort_write_group``
240
97
is called, at which time it is either finished and moved into place or
241
98
discarded respectively.  Write groups cannot be nested, only one can be
253
110
``packs/`` directory, but the file is needed for readonly http clients
254
111
that can't easily list directories, and it includes other information.)
255
112
The constraint on the ``pack-names`` list is that every file mentioned
256
 
must exist in the ``packs/`` directory.
 
113
must exist in the ``packs/`` directory.  
257
114
 
258
115
In rare cases, when a writer is interrupted, about-to-be-removed packs
259
116
may still be present in the directory but removed from the list.
283
140
However, in some circumstances we may want to garbage-collect or prune
284
141
existing data, or reconcile indexes.
285
142
 
286
 
..
287
 
   vim: tw=72 ft=rst expandtab
 
143
  vim: tw=72 ft=rest expandtab