|
2534.1.1
by Robert Collins
Create a document describing bundles and their motivation. |
1 |
======= |
2 |
Bundles |
|
3 |
======= |
|
4 |
||
5 |
Status |
|
6 |
====== |
|
7 |
||
8 |
:Date: 2007-06-19 |
|
9 |
||
10 |
This document describes the current and future design of the bzr bundle facility. |
|
11 |
||
12 |
.. contents:: |
|
13 |
||
14 |
Motivation |
|
15 |
========== |
|
16 |
||
17 |
Bundles are intended to be a compact binary representation of the changes done within |
|
18 |
a branch for transmission between users. Bundles should be able to be used |
|
19 |
easily and seamlessly - we want to avoid having a parallel set of commands to |
|
20 |
get data from within a bundle. |
|
21 |
||
22 |
A related concept is **merge directives** which are used to transmit bzr merge |
|
23 |
and merge-like operations from one user to another in such a way that the |
|
24 |
recipient can be sure they get the correct data the initiator desired. |
|
25 |
||
26 |
Desired features |
|
27 |
================ |
|
28 |
||
29 |
* A bundle should be able to substitute for the entire branch in any bzr |
|
30 |
command that operates on branches in a read only fashion. |
|
31 |
* Bundles should be as small as possible without losing data to keep them |
|
32 |
feasible for including in emails. |
|
33 |
||
34 |
Historical Design |
|
35 |
================= |
|
36 |
||
37 |
Not formally documented, the current released implementation can be found |
|
38 |
in bzrlib.bundle.serializer. One key element is that this design included |
|
39 |
parts of the branch data as human readable diffs; which were then subject |
|
40 |
to corruption by transports such as email. |
|
41 |
||
42 |
June 2007 Design |
|
43 |
================ |
|
44 |
||
45 |
To be documented. |
|
46 |
||
47 |
Future Plans |
|
48 |
============ |
|
49 |
||
50 |
Bundles will be implemented as a 'Shallow Branch' with the branch and |
|
51 |
repository data combined into a single file. This removes the need to |
|
52 |
special case bundle handling for all command which read from branches. |
|
53 |
||
54 |
Physical encoding |
|
55 |
----------------- |
|
56 |
||
57 |
Bundles will be encoded using the bzr pack format. Within the pack the |
|
58 |
branch metadata will be serialised as a BzrMetaDir1 branch entry. The |
|
59 |
Repository data added by the revisions contained in the bundle will be |
|
60 |
encoded using multi parent diffs as they are the most pithy diffs we are |
|
61 |
able to create today in the presence of merges. XXX More details needed? |
|
62 |
||
63 |
Code reuse |
|
64 |
---------- |
|
65 |
||
66 |
Ideally we can reuse our BzrMetaDir based branch formats directly within a |
|
67 |
Bundle by layering a Transport interface on top of the pack - or just |
|
68 |
copying the data out into a readonly memory transport when we read the |
|
69 |
pack. This suggests we will have a pack specific Control instance, |
|
70 |
replacing the usual 'BzrDir' instance, but use the Branch class as-is. |
|
71 |
||
72 |
For the Repository access, we will create a composite Repository using the |
|
73 |
planned Repository Stacking API, and a minimal Repository implementation |
|
74 |
that can work with the multi parent diffs within the bundle. |
|
75 |
||
76 |
We will need access to a branch that has the basis revision of the bundle |
|
77 |
to be able to construct revisions from within it - this is a requirement |
|
78 |
for Shallow Branches too, so hopefully we can define a single mechanism at |
|
79 |
the Branch level to gain access to that. |
|
80 |
||
81 |
||
82 |
vim: ft=rst tw=74 ai |
|
83 |