~bzr-pqm/bzr/bzr.dev : contents of doc/developers/bundles.txt at revision 4852.1.3

~bzr-pqm/bzr/bzr.dev : (revision 4852.1.3)

=======
Bundles 
=======

Status
======

:Date: 2007-06-19

This document describes the current and future design of the bzr bundle facility.

.. contents::

Motivation
==========

Bundles are intended to be a compact binary representation of the changes done within
a branch for transmission between users. Bundles should be able to be used
easily and seamlessly - we want to avoid having a parallel set of commands to
get data from within a bundle.

A related concept is **merge directives** which are used to transmit bzr merge
and merge-like operations from one user to another in such a way that the
recipient can be sure they get the correct data the initiator desired.

Desired features
================

* A bundle should be able to substitute for the entire branch in any bzr
  command that operates on branches in a read only fashion.
* Bundles should be as small as possible without losing data to keep them
  feasible for including in emails.

Historical Design
=================

Not formally documented, the current released implementation can be found
in bzrlib.bundle.serializer. One key element is that this design included
parts of the branch data as human readable diffs; which were then subject
to corruption by transports such as email.

June 2007 Design
================
`Bundle Format 4 spec`_

.. _Bundle Format 4 spec: bundle-format4.html


Future Plans
============

Bundles will be implemented as a 'Shallow Branch' with the branch and
repository data combined into a single file. This removes the need to
special case bundle handling for all command which read from branches.

Physical encoding
-----------------

Bundles will be encoded using the bzr pack format. Within the pack the
branch metadata will be serialised as a BzrMetaDir1 branch entry. The
Repository data added by the revisions contained in the bundle will be
encoded using multi parent diffs as they are the most pithy diffs we are
able to create today in the presence of merges. XXX More details needed?

Code reuse
----------

Ideally we can reuse our BzrMetaDir based branch formats directly within a
Bundle by layering a Transport interface on top of the pack - or just
copying the data out into a readonly memory transport when we read the
pack. This suggests we will have a pack specific Control instance,
replacing the usual 'BzrDir' instance, but use the Branch class as-is.

For the Repository access, we will create a composite Repository using the
planned Repository Stacking API, and a minimal Repository implementation
that can work with the multi parent diffs within the bundle.

We will need access to a branch that has the basis revision of the bundle
to be able to construct revisions from within it - this is a requirement
for Shallow Branches too, so hopefully we can define a single mechanism at
the Branch level to gain access to that.


..
   vim: ft=rst tw=74 ai

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	================
2520.4.129 by Aaron Bentley update docs	44	`Bundle Format 4 spec`_
2520.4.129 by Aaron Bentley update docs	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