← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/knitpack.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-11-04 18:51:39 UTC
  • mfrom: (2961.1.1 trunk)
  • Revision ID: pqm@pqm.ubuntu.com-20071104185139-kaio3sneodg2kp71
Authentication ring implementation (read-only)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/knitpack.txt
42
42
``knitpack`` one. Here's how::
43
43
 
44
44
  cd my-stuff
45
 
  bzr init --pack-0.92
 
45
  bzr init --knitpack-experimental
46
46
  bzr add
47
47
  bzr commit -m "initial import"
48
48
 
49
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``.
 
50
``--knitpack-experimental`` option to the ``init`` command.
53
51
 
54
52
Creating a new knitpack repository
55
53
----------------------------------
58
56
for branches, you can make it a ``knitpack`` repository like this::
59
57
 
60
58
  cd my-repo
61
 
  bzr init-repo --pack-0.92 .
 
59
  bzr init-repo --knitpack-experimental .
62
60
  cd my-stuff
63
61
  bzr init
64
62
  bzr add
65
63
  bzr commit -m "initial import"
66
64
 
67
65
In other words, use the normal sequence of commands but add the
68
 
``--pack-0.92`` option to the ``init-repo`` command.
 
66
``--knitpack-experimental`` option to the ``init-repo`` command.
69
67
 
70
68
Upgrading an existing branch or repository to knitpack format
71
69
-------------------------------------------------------------
73
71
If you have an existing branch and wish to migrate it to
74
72
a ``knitpack`` format, use the ``upgrade`` command like this::
75
73
 
76
 
  bzr upgrade --pack-0.92 path-to-my-branch
 
74
  bzr upgrade --knitpack-experimental path-to-my-branch
77
75
 
78
76
If you are using a shared repository, run::
79
77
 
80
 
  bzr upgrade --pack-0.92 ROOT_OF_REPOSITORY
 
78
  bzr upgrade --knitpack-experimental ROOT_OF_REPOSITORY
81
79
 
82
80
to upgrade the history database. Note that this will not
83
81
alter the branch format of each branch, so
97
95
 
98
96
Here are the commands for using the ``pull`` approach::
99
97
 
100
 
    bzr init --pack-0.92 my-new-branch
 
98
    bzr init --knitpack-experimental my-new-branch
101
99
    cd my-new-branch
102
100
    bzr pull my-source-branch
103
101
 
105
103
 
106
104
    bzr branch my-source-branch my-new-branch
107
105
    cd my-new-branch
108
 
    bzr upgrade --pack-0.92 .
 
106
    bzr upgrade --knitpack-experimental .
109
107
 
110
108
Here are the commands for the shared repository approach::
111
109
 
112
110
  cd my-repo
113
 
  bzr init-repo --pack-0.92 .
 
111
  bzr init-repo --knitpack-experimental .
114
112
  bzr branch my-source-branch my-new-branch
115
113
  cd my-new-branch
116
 
 
 
114
 
117
115
As a reminder, any of the above approaches can fail if the source branch
118
116
has inconsistent data within it and hasn't been reconciled yet. Please
119
117
be sure to check that before reporting problems.
126
124
are identical to the ones given above except that the name of the format
127
125
to use is ``knitpack-subtree-experimental``.
128
126
 
129
 
WARNING: Note that the subtree formats, ``dirstate-subtree`` and
 
127
WARNING: Note that the subtree formats, ``distate-subtree`` and
130
128
``knitpack-subtree-experimental``, are **not** production strength yet and
131
129
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
 
130
plug-in but should otherwise ony be used by people happy to live on the
133
131
bleeding edge. If you are using bzr-svn, you're on the bleeding edge anyway.
134
132
:-)
135
133
 
145
143
===============
146
144
 
147
145
Bazaar 0.92 adds a new format (experimental at first) implemented in
148
 
``bzrlib.repofmt.pack_repo.py``.
 
146
``bzrlib.repofmt.pack_repo.py``.  
149
147
 
150
148
This format provides a knit-like interface which is quite compatible
151
149
with knit format repositories: you can get a VersionedFile for a
158
156
==================== =============================================
159
157
packs/               completed readonly packs
160
158
indices/             indices for completed packs
161
 
upload/              temporary files for packs currently being
 
159
upload/              temporary files for packs currently being 
162
160
                     written
163
 
obsolete_packs/      packs that have been repacked and are no
 
161
obsolete_packs/      packs that have been repacked and are no 
164
162
                     longer normally needed
165
163
pack-names           index of all live packs
166
164
lock/                lockdir
186
184
                                             compression base
187
185
======== ========== ======================== ==========================
188
186
 
189
 
Indices are accessed through the ``bzrlib.index.GraphIndex`` class.
 
187
Indices are accessed through the ``bzrlib.index.GraphIndex`` class.  
190
188
Indices are stored as sorted files on disk.  Each line is one record,
191
189
and contains:
192
190
 
193
191
 * key fields
194
192
 * 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
 
193
   of "offset length" giving the position of the refenced data within 
196
194
   the pack body file
197
195
 * a list of zero or more reference lists
198
196
 
221
219
 
222
220
It is not possible to regenerate an index from the body file, because it
223
221
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.)
 
222
(In particular, the per-file graph is only stored in the index.) 
225
223
We would like to change this in a future format.
226
224
 
227
225
The lock is a regular LockDir lock.  The lock is only held for a much
229
227
insertion can be done without the repository locked.  This is an
230
228
implementation detail; the repository user should still call
231
229
``repository.lock_write`` at the regular time but be aware this does not
232
 
correspond to a physical mutex.
 
230
correspond to a physical mutex. 
233
231
 
234
232
Read locks control caching but do not affect writers.
235
233
 
236
234
The newly-added repository write group concept is very important to
237
235
KnitPack repositories.  When ``start_write_group`` is called, a new
238
 
temporary pack is created and all modifications to the repository will
 
236
temporary pack is created and all modifications to the repository will 
239
237
go into it until either ``commit_write_group`` or ``abort_write_group``
240
238
is called, at which time it is either finished and moved into place or
241
239
discarded respectively.  Write groups cannot be nested, only one can be
253
251
``packs/`` directory, but the file is needed for readonly http clients
254
252
that can't easily list directories, and it includes other information.)
255
253
The constraint on the ``pack-names`` list is that every file mentioned
256
 
must exist in the ``packs/`` directory.
 
254
must exist in the ``packs/`` directory.  
257
255
 
258
256
In rare cases, when a writer is interrupted, about-to-be-removed packs
259
257
may still be present in the directory but removed from the list.
283
281
However, in some circumstances we may want to garbage-collect or prune
284
282
existing data, or reconcile indexes.
285
283
 
286
 
..
287
 
   vim: tw=72 ft=rst expandtab
 
284
  vim: tw=72 ft=rest expandtab