<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Bundles — Bazaar 2.6.0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.6.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="top" title="Bazaar 2.6.0 documentation" href="index.html" />
<link rel="up" title="Specifications" href="specifications.html" />
<link rel="next" title="Container format" href="container-format.html" />
<link rel="prev" title="Authentication ring" href="authentication-ring.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="container-format.html" title="Container format"
accesskey="N">next</a></li>
<li class="right" >
<a href="authentication-ring.html" title="Authentication ring"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="index.html">Developer Document Catalog (2.6.0)</a> »</li>
<li><a href="specifications.html" accesskey="U">Specifications</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bundles">
<h1><a class="toc-backref" href="#id1">Bundles</a><a class="headerlink" href="#bundles" title="Permalink to this headline">¶</a></h1>
<div class="section" id="status">
<h2><a class="toc-backref" href="#id2">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Date:</th><td class="field-body">2007-06-19</td>
</tr>
</tbody>
</table>
<p>This document describes the current and future design of the bzr bundle facility.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#bundles" id="id1">Bundles</a><ul>
<li><a class="reference internal" href="#status" id="id2">Status</a></li>
<li><a class="reference internal" href="#motivation" id="id3">Motivation</a></li>
<li><a class="reference internal" href="#desired-features" id="id4">Desired features</a></li>
<li><a class="reference internal" href="#historical-design" id="id5">Historical Design</a></li>
<li><a class="reference internal" href="#june-2007-design" id="id6">June 2007 Design</a></li>
<li><a class="reference internal" href="#future-plans" id="id7">Future Plans</a><ul>
<li><a class="reference internal" href="#physical-encoding" id="id8">Physical encoding</a></li>
<li><a class="reference internal" href="#code-reuse" id="id9">Code reuse</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="section" id="motivation">
<h2><a class="toc-backref" href="#id3">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>A related concept is <strong>merge directives</strong> 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.</p>
</div>
<div class="section" id="desired-features">
<h2><a class="toc-backref" href="#id4">Desired features</a><a class="headerlink" href="#desired-features" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>A bundle should be able to substitute for the entire branch in any bzr
command that operates on branches in a read only fashion.</li>
<li>Bundles should be as small as possible without losing data to keep them
feasible for including in emails.</li>
</ul>
</div>
<div class="section" id="historical-design">
<h2><a class="toc-backref" href="#id5">Historical Design</a><a class="headerlink" href="#historical-design" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
</div>
<div class="section" id="june-2007-design">
<h2><a class="toc-backref" href="#id6">June 2007 Design</a><a class="headerlink" href="#june-2007-design" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="bundle-format4.html">Bundle Format 4 spec</a></p>
</div>
<div class="section" id="future-plans">
<h2><a class="toc-backref" href="#id7">Future Plans</a><a class="headerlink" href="#future-plans" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<div class="section" id="physical-encoding">
<h3><a class="toc-backref" href="#id8">Physical encoding</a><a class="headerlink" href="#physical-encoding" title="Permalink to this headline">¶</a></h3>
<p>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?</p>
</div>
<div class="section" id="code-reuse">
<h3><a class="toc-backref" href="#id9">Code reuse</a><a class="headerlink" href="#code-reuse" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Bundles</a><ul>
<li><a class="reference internal" href="#status">Status</a></li>
<li><a class="reference internal" href="#motivation">Motivation</a></li>
<li><a class="reference internal" href="#desired-features">Desired features</a></li>
<li><a class="reference internal" href="#historical-design">Historical Design</a></li>
<li><a class="reference internal" href="#june-2007-design">June 2007 Design</a></li>
<li><a class="reference internal" href="#future-plans">Future Plans</a><ul>
<li><a class="reference internal" href="#physical-encoding">Physical encoding</a></li>
<li><a class="reference internal" href="#code-reuse">Code reuse</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="authentication-ring.html"
title="previous chapter">Authentication ring</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="container-format.html"
title="next chapter">Container format</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/bundles.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="container-format.html" title="Container format"
>next</a></li>
<li class="right" >
<a href="authentication-ring.html" title="Authentication ring"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li><a href="index.html">Developer Document Catalog (2.6.0)</a> »</li>
<li><a href="specifications.html" >Specifications</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
