<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using stacked branches — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/bzr.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Running a smart server" href="server.html" />
<link rel="prev" title="Filtered views" href="filtered_views.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="server.html" title="Running a smart server"
accesskey="N">next</a></li>
<li class="right" >
<a href="filtered_views.html" title="Filtered views"
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 class="nav-item nav-item-0"><a href="../index.html">Table of Contents (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Bazaar User Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="using-stacked-branches">
<h1>Using stacked branches<a class="headerlink" href="#using-stacked-branches" title="Permalink to this headline">¶</a></h1>
<div class="section" id="motivation">
<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
<p>If you are working on a project, and you have read access to whose
public repository but do not have write access to it, using stacked
branches to backup/publish your work onto the same host of the public
repository might be an option for you.</p>
<p>Other scenarios for stacked branch usage include experimental branches
and code hosting sites. For these scenarios, stacked branches are
ideal because of the benefits it provides.</p>
</div>
<div class="section" id="what-is-a-stacked-branch">
<h2>What is a stacked branch?<a class="headerlink" href="#what-is-a-stacked-branch" title="Permalink to this headline">¶</a></h2>
<p>A stacked branch is a branch that knows how to find revisions in
another branch (the stacked-on branch). Stacked branches store just
the unique revisions that are not in the stacked-on branch, making
them faster to create and more storage efficient. In these respects,
stacked branches are similar to shared repositories. However, stacked
branches have additional benefits:</p>
<ul class="simple">
<li>The new branch can be in a completely different location to the
branch being stacked on.</li>
<li>Deleting the stacked branch really deletes the revisions (rather
than leaving them in a shared repository).</li>
<li>Security is improved over shared repositories, because the stacked-on
repository can be physically readonly to developers committing to stacked
branches.</li>
</ul>
</div>
<div class="section" id="creating-a-stacked-branch">
<h2>Creating a stacked branch<a class="headerlink" href="#creating-a-stacked-branch" title="Permalink to this headline">¶</a></h2>
<p>To create a stacked branch, use the <code class="docutils literal notranslate"><span class="pre">stacked</span></code> option of the branch command.
For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">branch</span> <span class="o">--</span><span class="n">stacked</span> <span class="n">source</span><span class="o">-</span><span class="n">url</span> <span class="n">my</span><span class="o">-</span><span class="nb">dir</span>
</pre></div>
</div>
<p>This will create <code class="docutils literal notranslate"><span class="pre">my-dir</span></code> as a stacked branch with no local revisions.
If it is defined, the public branch associated with <code class="docutils literal notranslate"><span class="pre">source-url</span></code> will be
used as the <em>stacked-on</em> location. Otherwise, <code class="docutils literal notranslate"><span class="pre">source-url</span></code> will be the
<em>stacked-on</em> location.</p>
</div>
<div class="section" id="creating-a-stacked-checkout">
<h2>Creating a stacked checkout<a class="headerlink" href="#creating-a-stacked-checkout" title="Permalink to this headline">¶</a></h2>
<p>Direct creation of a stacked checkout is expected to be supported soon.
In the meantime, a two step process is required:</p>
<ol class="arabic simple">
<li>Create a stacked branch as shown above.</li>
<li>Convert the branch into a checkout using either the <code class="docutils literal notranslate"><span class="pre">reconfigure</span></code>
or <code class="docutils literal notranslate"><span class="pre">bind</span></code> command.</li>
</ol>
</div>
<div class="section" id="pushing-a-stacked-branch">
<h2>Pushing a stacked branch<a class="headerlink" href="#pushing-a-stacked-branch" title="Permalink to this headline">¶</a></h2>
<p>Most changes on most projects build on an existing branch such as the
<em>development trunk</em> or <em>current stable</em> branch. Creating a new
branch stacked on one of these is easy to do using the <code class="docutils literal notranslate"><span class="pre">push</span></code>
command like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">push</span> <span class="o">--</span><span class="n">stacked</span><span class="o">-</span><span class="n">on</span> <span class="n">reference</span><span class="o">-</span><span class="n">url</span> <span class="n">my</span><span class="o">-</span><span class="n">url</span>
</pre></div>
</div>
<p>This creates a new branch at <code class="docutils literal notranslate"><span class="pre">my-url</span></code> that is stacked on <code class="docutils literal notranslate"><span class="pre">reference-url</span></code>
and only contains the revisions in the current branch that are not already
in the branch at <code class="docutils literal notranslate"><span class="pre">reference-url</span></code>. In particular, <code class="docutils literal notranslate"><span class="pre">my-url</span></code> and
<code class="docutils literal notranslate"><span class="pre">reference-url</span></code> can be on the same host, and the <code class="docutils literal notranslate"><span class="pre">--stacked-on</span></code> option
can be used additionally to inform <code class="docutils literal notranslate"><span class="pre">push</span></code> to reference the
revisions in <code class="docutils literal notranslate"><span class="pre">reference-url</span></code>. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">push</span> <span class="o">--</span><span class="n">stacked</span><span class="o">-</span><span class="n">on</span> <span class="n">bzr</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="o">/</span><span class="n">project</span> <span class="n">bzr</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">host</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">stacked</span><span class="o">-</span><span class="n">branch</span>
</pre></div>
</div>
<p>This usage fits the scenario described in the Motivation section.</p>
<p>You can also use the <code class="docutils literal notranslate"><span class="pre">--stacked</span></code> option without specifying <code class="docutils literal notranslate"><span class="pre">--stacked-on</span></code>.
This will automatically set the <em>stacked-on</em> location to the parent branch of
the branch you are pushing (or its <code class="docutils literal notranslate"><span class="pre">public_location</span></code> if configured). For
example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">branch</span> <span class="n">source</span><span class="o">-</span><span class="n">url</span> <span class="n">my</span><span class="o">-</span><span class="nb">dir</span>
<span class="n">cd</span> <span class="n">my</span><span class="o">-</span><span class="nb">dir</span>
<span class="p">(</span><span class="n">hack</span><span class="p">,</span> <span class="n">hack</span><span class="p">,</span> <span class="n">hack</span><span class="p">)</span>
<span class="n">bzr</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">"fix bug"</span>
<span class="n">bzr</span> <span class="n">push</span> <span class="o">--</span><span class="n">stacked</span>
</pre></div>
</div>
<p>You can combine <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">branch</span> <span class="pre">--stacked</span></code> and <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">push</span> <span class="pre">--stacked</span></code> to work on a
branch without downloading or uploading the whole history:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">branch</span> <span class="o">--</span><span class="n">stacked</span> <span class="n">source</span><span class="o">-</span><span class="n">url</span> <span class="n">my</span><span class="o">-</span><span class="nb">dir</span>
<span class="n">cd</span> <span class="n">my</span><span class="o">-</span><span class="nb">dir</span>
<span class="p">(</span><span class="n">hack</span><span class="p">,</span> <span class="n">hack</span><span class="p">,</span> <span class="n">hack</span><span class="p">)</span>
<span class="n">bzr</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">"fix bug"</span>
<span class="n">bzr</span> <span class="n">push</span> <span class="o">--</span><span class="n">stacked</span>
</pre></div>
</div>
</div>
<div class="section" id="limitations-of-stacked-branches">
<h2>Limitations of stacked branches<a class="headerlink" href="#limitations-of-stacked-branches" title="Permalink to this headline">¶</a></h2>
<p>The important thing to remember about a stacked branch is that the stacked-on
branch needs to be accessible for almost all operations. This is not an issue
when both branches are local, or when both branches are on the same server and
the stacked-on location is a relative path. But clearly a branch hosted on a
server with a stacked-on location of <code class="docutils literal notranslate"><span class="pre">file:///...</span></code> is not going to work for
anyone except the user that originally pushed it. It’s a good idea to configure
<code class="docutils literal notranslate"><span class="pre">public_location</span></code> to help prevent that.</p>
<p>Similarly, because most of the history is stored in the stacked-on repository,
operations like <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">log</span></code> can be slower when the stacked-on repository is
accessed via a network.</p>
<p>If a stacked branch is in a format older than 2a, you cannot commit to it due to
<a class="reference external" href="https://bugs.launchpad.net/bzr/+bug/375013">bug 375013</a>.</p>
</div>
<div class="section" id="changing-branch-stacking">
<h2>Changing branch stacking<a class="headerlink" href="#changing-branch-stacking" title="Permalink to this headline">¶</a></h2>
<p>Stacking of existing branches can be changed using the <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">reconfigure</span></code>
command to either stack on an existing branch, or to turn off stacking.
Be aware that when <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">reconfigure</span> <span class="pre">--unstacked</span></code> is used, bzr will
copy all the referenced data from the stacked-on repository into the
previously stacked repository. For large repositories this may take
considerable time and may substantially increase the size of the
repository.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using stacked branches</a><ul>
<li><a class="reference internal" href="#motivation">Motivation</a></li>
<li><a class="reference internal" href="#what-is-a-stacked-branch">What is a stacked branch?</a></li>
<li><a class="reference internal" href="#creating-a-stacked-branch">Creating a stacked branch</a></li>
<li><a class="reference internal" href="#creating-a-stacked-checkout">Creating a stacked checkout</a></li>
<li><a class="reference internal" href="#pushing-a-stacked-branch">Pushing a stacked branch</a></li>
<li><a class="reference internal" href="#limitations-of-stacked-branches">Limitations of stacked branches</a></li>
<li><a class="reference internal" href="#changing-branch-stacking">Changing branch stacking</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="filtered_views.html"
title="previous chapter">Filtered views</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="server.html"
title="next chapter">Running a smart server</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/user-guide/stacked.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<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>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="server.html" title="Running a smart server"
>next</a></li>
<li class="right" >
<a href="filtered_views.html" title="Filtered views"
>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 class="nav-item nav-item-0"><a href="../index.html">Table of Contents (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Bazaar User Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
