← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/packrepo.txt

  • Committer: Tarmac
  • Author(s): Vincent Ladeuil
  • Date: 2017-01-30 14:42:05 UTC
  • mfrom: (6620.1.1 trunk)
  • Revision ID: tarmac-20170130144205-r8fh2xpmiuxyozpv
Merge  2.7 into trunk including fix for bug #1657238 [r=vila]

Show diffs side-by-side

added added

removed removed

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