|
2534.1.1
by Robert Collins
Create a document describing bundles and their motivation. |
1 |
======= |
|
4853.1.1
by Patrick Regan
Removed trailing whitespace from files in doc directory |
2 |
Bundles |
|
2534.1.1
by Robert Collins
Create a document describing bundles and their motivation. |
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 |
================ |
|
|
2520.4.129
by Aaron Bentley
update docs |
44 |
`Bundle Format 4 spec`_ |
45 |
||
|
2666.2.1
by Alexander Belchenko
change generated documentation extension from htm to html |
46 |
.. _Bundle Format 4 spec: bundle-format4.html |
|
2520.4.129
by Aaron Bentley
update docs |
47 |
|
|
2534.1.1
by Robert Collins
Create a document describing bundles and their motivation. |
48 |
|
49 |
Future Plans |
|
50 |
============ |
|
51 |
||
52 |
Bundles will be implemented as a 'Shallow Branch' with the branch and |
|
53 |
repository data combined into a single file. This removes the need to |
|
54 |
special case bundle handling for all command which read from branches. |
|
55 |
||
56 |
Physical encoding |
|
57 |
----------------- |
|
58 |
||
59 |
Bundles will be encoded using the bzr pack format. Within the pack the |
|
60 |
branch metadata will be serialised as a BzrMetaDir1 branch entry. The |
|
61 |
Repository data added by the revisions contained in the bundle will be |
|
62 |
encoded using multi parent diffs as they are the most pithy diffs we are |
|
63 |
able to create today in the presence of merges. XXX More details needed? |
|
64 |
||
65 |
Code reuse |
|
66 |
---------- |
|
67 |
||
68 |
Ideally we can reuse our BzrMetaDir based branch formats directly within a |
|
69 |
Bundle by layering a Transport interface on top of the pack - or just |
|
70 |
copying the data out into a readonly memory transport when we read the |
|
71 |
pack. This suggests we will have a pack specific Control instance, |
|
72 |
replacing the usual 'BzrDir' instance, but use the Branch class as-is. |
|
73 |
||
74 |
For the Repository access, we will create a composite Repository using the |
|
75 |
planned Repository Stacking API, and a minimal Repository implementation |
|
76 |
that can work with the multi parent diffs within the bundle. |
|
77 |
||
78 |
We will need access to a branch that has the basis revision of the bundle |
|
79 |
to be able to construct revisions from within it - this is a requirement |
|
80 |
for Shallow Branches too, so hopefully we can define a single mechanism at |
|
81 |
the Branch level to gain access to that. |
|
82 |
||
83 |
||
|
3052.6.2
by John Arbash Meinel
Clean up some vim: lines to make them proper ReST comments. |
84 |
.. |
|
2534.1.1
by Robert Collins
Create a document describing bundles and their motivation. |
85 |
vim: ft=rst tw=74 ai |