<!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>Advanced shared repository layouts — Bazaar v2.4.2 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.4.2',
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 v2.4.2 documentation" href="../index.html" />
<link rel="up" title="Bazaar User Guide" href="index.html" />
<link rel="next" title="Configuring email" href="setting_up_email.html" />
<link rel="prev" title="Organizing your workspace" href="organizing_your_workspace.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="setting_up_email.html" title="Configuring email"
accesskey="N">next</a></li>
<li class="right" >
<a href="organizing_your_workspace.html" title="Organizing your workspace"
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">Table of Contents (2.4.2)</a> »</li>
<li><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">
<div class="section" id="advanced-shared-repository-layouts">
<h1>Advanced shared repository layouts<a class="headerlink" href="#advanced-shared-repository-layouts" title="Permalink to this headline">¶</a></h1>
<p>Bazaar is designed to give you flexibility in how you layout branches inside a shared repository.
This flexibility allows users to tailor Bazaar to their workflow,
but it also leads to questions about what is a “good” layout.
We present some alternatives and give some discussion about the benefits of each.</p>
<p>One key point which should be mentioned is that any good layout should somehow highlight
what branch a “general” user should grab. In SVN this is deemed the “<tt class="docutils literal"><span class="pre">trunk/</span></tt>” branch,
and in most of the layouts this naming convention is preserved. Some would call this
“<tt class="docutils literal"><span class="pre">mainline</span></tt>” or “<tt class="docutils literal"><span class="pre">dev</span></tt>”, and people from CVS often refer to this as “<tt class="docutils literal"><span class="pre">HEAD</span></tt>”.</p>
<div class="section" id="svn-style-trunk-branches">
<h2>“SVN-Style” (<tt class="docutils literal"><span class="pre">trunk/</span></tt>, <tt class="docutils literal"><span class="pre">branches/</span></tt>)<a class="headerlink" href="#svn-style-trunk-branches" title="Permalink to this headline">¶</a></h2>
<p>Most people coming from SVN will be familiar with their “standard” project layout.
Which is to layout the repository as:</p>
<div class="highlight-python"><pre>repository/ # Overall repository
+- trunk/ # The mainline of development
+- branches/ # A container directory
| +- foo/ # Branch for developing feature foo
| ...
+- tags/ # Container directory
+- release-X # A branch specific to mark a given release version
...</pre>
</div>
<p>With Bazaar, that is a perfectly reasonable layout.
It has the benefit of being familiar to people coming from SVN,
and making it clear where the development focus is.</p>
<p>When you have multiple projects in the same repository,
the SVN layout is a little unclear what to do.</p>
<div class="section" id="project-trunk">
<h3><tt class="docutils literal"><span class="pre">project/trunk</span></tt><a class="headerlink" href="#project-trunk" title="Permalink to this headline">¶</a></h3>
<p>The preferred method for SVN seems to be to give each project a top level directory for a layout like:</p>
<div class="highlight-python"><pre>repository/ # Overall repository
+- project1/ # A container directory
| +- trunk/ # The mainline of development of project1
| +- branches/ # A container directory
| +- foo/ # Branch for developing feature foo of project1
| ...
|
+- project2/ # Container for project2
+- trunk/ # Mainline for project2
+- branches/ # Container for project2 branches</pre>
</div>
<p>This also works with Bazaar.
However, with Bazaar repositories are cheap to create
(a simple <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">init-repo</span></tt> away), and their primary benefit is when the
branches share a common ancestry.</p>
<p>So the preferred way for Bazaar would be:</p>
<div class="highlight-python"><pre>project1/ # A repository for project1
+- trunk/ # The mainline of development of project1
+- branches/ # A container directory
+- foo/ # Branch for developing feature foo of project1
...
project2/ # A repository for project2
+- trunk/ # Mainline for project2
+- branches/ # Container for project2 branches</pre>
</div>
</div>
<div class="section" id="trunk-project">
<h3><tt class="docutils literal"><span class="pre">trunk/project</span></tt><a class="headerlink" href="#trunk-project" title="Permalink to this headline">¶</a></h3>
<p>There are also a few projects who use this layout in SVN:</p>
<div class="highlight-python"><pre>repository/ # Overall repository
+- trunk/ # A container directory
| +- project1 # Mainline for project 1
| +- project2 # Mainline for project 2
| ...
|
+- branches/ # Container
+- project1/ # Container (?)
| +- foo # Branch 'foo' of project1
+- project2/
+- bar # Branch 'bar' of project2</pre>
</div>
<p>A slight variant is:</p>
<div class="highlight-python"><pre>repository/ # Overall repository
+- trunk/ # A container directory
| +- project1 # Mainline for project 1
| +- project2 # Mainline for project 2
| ...
|
+- branches/ # Container
+- project1-foo/ # Branch 'foo' of project1
+- project2-bar/ # Branch 'bar' of project2</pre>
</div>
<p>I believe the reason for this in SVN, is so that someone
can checkout all of “<tt class="docutils literal"><span class="pre">trunk/</span></tt>” and get the all the mainlines for all projects.</p>
<p>This layout can be used for Bazaar, but it is not generally recommended.</p>
<blockquote>
<div><ol class="arabic simple">
<li><tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">branch/checkout/get</span></tt> is a single branch at a time.
So you don’t get the benefit of getting all mainlines with a single command. <a class="footnote-reference" href="#id2" id="id1">[1]</a></li>
<li>It is less obvious of whether <tt class="docutils literal"><span class="pre">repository/trunk/foo</span></tt> is the <tt class="docutils literal"><span class="pre">trunk</span></tt> of project
<tt class="docutils literal"><span class="pre">foo</span></tt> or it is just the <tt class="docutils literal"><span class="pre">foo</span></tt> directory in the <tt class="docutils literal"><span class="pre">trunk</span></tt> branch.
Some of this confusion is due to SVN, because it uses the same “namespace”
for files in a project that it uses for branches of a project.
In Bazaar, there is a clear distinction of what files make up a project, versus
the location of the Branch. (After all, there is only one <tt class="docutils literal"><span class="pre">.bzr/</span></tt> directory per branch,
versus many <tt class="docutils literal"><span class="pre">.svn/</span></tt> directories in the checkout).</li>
</ol>
</div></blockquote>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Note: <a class="reference external" href="http://wiki.bazaar.canonical.com/NestedTrees">NestedTreeSupport</a> can provide a way to create “meta-projects” which
aggregate multiple projects regardless of the repository layout.
Letting you <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">checkout</span></tt> one project, and have it grab all the necessary
sub-projects.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="nested-style-project-branch-sub-branch">
<h2>Nested Style (<tt class="docutils literal"><span class="pre">project/branch/sub-branch/</span></tt>)<a class="headerlink" href="#nested-style-project-branch-sub-branch" title="Permalink to this headline">¶</a></h2>
<p>Another style with Bazaar, which is not generally possible in SVN
is to have branches nested within each-other.
This is possible because Bazaar supports (and recommends) creating repositories
with no working trees (<tt class="docutils literal"><span class="pre">--no-trees</span></tt>).
With a <tt class="docutils literal"><span class="pre">--no-trees</span></tt> repository, because the working files are not intermixed with
your branch locations, you are free to put a branch in whatever namespace you want.</p>
<p>One possibility is:</p>
<div class="highlight-python"><pre>project/ # The overall repository, *and* the project's mainline branch
+ joe/ # Developer Joe's primary branch of development
| +- feature1/ # Developer Joe's feature1 development branch
| | +- broken/ # A staging branch for Joe to develop feature1
| +- feature2/ # Joe's feature2 development branch
| ...
+ barry/ # Barry's development branch
| ...
+ releases/
+- 1.0/
+- 1.1.1/</pre>
</div>
<p>The idea with this layout is that you are creating a hierarchical layout for branches.
Where changes generally flow upwards in the namespace. It also gives people a little
corner of the namespace to work on their stuff.
One nice feature of this layout, is it makes branching “cheaper” because it gives you
a place to put all the mini branches without cluttering up the global <tt class="docutils literal"><span class="pre">branches/</span></tt> namespace.</p>
<p>The other power of this is that you don’t have to repeat yourself when specifying more detail in the
branch name.</p>
<p>For example compare:</p>
<div class="highlight-python"><pre>bzr branch http://host/repository/project/branches/joe-feature-foo-bugfix-10/</pre>
</div>
<p>Versus:</p>
<div class="highlight-python"><pre>bzr branch http://host/project/joe/foo/bugfix-10</pre>
</div>
<p>Also, if you list the <tt class="docutils literal"><span class="pre">repository/project/branches/</span></tt> directory you might see something like:</p>
<div class="highlight-python"><pre>barry-feature-bar/
barry-bugfix-10/
barry-bugfix-12/
joe-bugfix-10/
joe-bugfix-13/
joe-frizban/</pre>
</div>
<p>Versus having these broken out by developer.
If the number of branches are small, <tt class="docutils literal"><span class="pre">branches/</span></tt> has the nice advantage
of being able to see all branches in a single view.
If the number of branches is large, <tt class="docutils literal"><span class="pre">branches/</span></tt> has the distinct disadvantage
of seeing all the branches in a single view (it becomes difficult to find the
branch you are interested in, when there are 100 branches to look through).</p>
<p>Nested branching seems to scale better to larger number of branches.
However, each individual branch is less discoverable.
(eg. “Is Joe working on bugfix 10 in his feature foo branch, or his feature bar branch?”)</p>
<p>One other small advantage is that you can do something like:</p>
<div class="highlight-python"><pre> bzr branch http://host/project/release/1/1/1
or
bzr branch http://host/project/release/1/1/2</pre>
</div>
<p>To indicate release 1.1.1 and 1.1.2. This again depends on how many releases you have
and whether the gain of splitting things up outweighs the ability to see more at a glance.</p>
</div>
<div class="section" id="sorted-by-status-dev-merged-experimental">
<h2>Sorted by Status (<tt class="docutils literal"><span class="pre">dev/</span></tt>, <tt class="docutils literal"><span class="pre">merged/</span></tt>, <tt class="docutils literal"><span class="pre">experimental/</span></tt>)<a class="headerlink" href="#sorted-by-status-dev-merged-experimental" title="Permalink to this headline">¶</a></h2>
<p>One other way to break up branches is to sort them by their current status.
So you would end up with a layout something like:</p>
<div class="highlight-python"><pre>project/ # Overall layout
+- trunk/ # The development focus branch
+- dev/ # Container directory for in-progress work
| +- joe-feature1 # Joe's current feature-1 branch
| +- barry-bugfix10 # Barry's work for bugfix 10
| ...
+- merged/ # Container indicating these branches have been merged
| +- bugfix-12 # Bugfix which has already been merged.
+- abandonded/ # Branches which are considered 'dead-end'</pre>
</div>
<p>This has a couple benefits and drawbacks.
It lets you see what branches are actively being developed on, which is usually
only a small number, versus the total number of branches ever created.
Old branches are not lost (versus deleting them), but they are “filed away”,
such that the more likely you are to want a branch the easier it is to find.
(Conversely, older branches are likely to be harder to find).</p>
<p>The biggest disadvantage with this layout, is that branches move around.
Which means that if someone is following the <tt class="docutils literal"><span class="pre">project/dev/new-feature</span></tt> branch,
when it gets merged into <tt class="docutils literal"><span class="pre">trunk/</span></tt> suddenly <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">pull</span></tt> doesn’t mirror the branch
for them anymore because the branch is now at <tt class="docutils literal"><span class="pre">project/merged/new-feature</span></tt>.
There are a couple ways around this. One is to use HTTP redirects to point people
requesting the old branch to the new branch. <tt class="docutils literal"><span class="pre">bzr</span></tt> >= 0.15 will let users know
that <tt class="docutils literal"><span class="pre">http://old/path</span> <span class="pre">redirects</span> <span class="pre">to</span> <span class="pre">http://new/path</span></tt>. However, this doesn’t help
if people are accessing a branch through methods other than HTTP (SFTP, local filesystem, etc).</p>
<p>It would also be possible to use a symlink for temporary redirecting (as long as the symlink
is within the repository it should cause little trouble). However eventually you want to
remove the symlink, or you don’t get the clutter reduction benefit.
Another possibility instead of a symlink is to use a <tt class="docutils literal"><span class="pre">BranchReference</span></tt>. It is currently
difficult to create these through the <tt class="docutils literal"><span class="pre">bzr</span></tt> command line, but if people find them useful
that could be changed.
This is actually how <a class="reference external" href="https://launchpad.net">Launchpad</a> allows you to <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">checkout</span> <span class="pre">https://launchpad.net/bzr</span></tt>.
Effectively a <tt class="docutils literal"><span class="pre">BranchReference</span></tt> is a symlink, but it allows you to reference any other URL.
If it is extended to support relative references, it would even work over HTTP, SFTP,
and local paths.</p>
</div>
<div class="section" id="sorted-by-date-release-etc-2006-06-2006-07-0-8-0-9">
<h2>Sorted by date/release/etc (<tt class="docutils literal"><span class="pre">2006-06/</span></tt>, <tt class="docutils literal"><span class="pre">2006-07/</span></tt>, <tt class="docutils literal"><span class="pre">0.8/</span></tt>, <tt class="docutils literal"><span class="pre">0.9</span></tt>)<a class="headerlink" href="#sorted-by-date-release-etc-2006-06-2006-07-0-8-0-9" title="Permalink to this headline">¶</a></h2>
<p>Another method of allowing some scalability while also allowing the
browsing of “current” branches. Basically, this works on the assumption
that actively developed branches will be “new” branches, and older branches
are either merged or abandoned.</p>
<p>Basically the date layout looks something like:</p>
<div class="highlight-python"><pre>project/ # Overall project repository
+- trunk/ # General mainline
+- 2006-06/ # containing directory for branches created in this month
| +- feature1/ # Branch of "project" for "feature1"
| +- feature2/ # Branch of "project" for "feature2"
+- 2005-05/ # Containing directory for branches create in a different month
+- feature3/
...</pre>
</div>
<p>This answers the question “Where should I put my new branch?” very quickly.
If a feature is developed for a long time, it is even reasonable to copy a
branch into the newest date, and continue working on it there.
Finding an active branch generally means going to the newest date, and
going backwards from there. (A small disadvantage is that most directory
listings sort oldest to the top, which may mean more scrolling).
If you don’t copy old branches to newer locations, it also has the disadvantage
that searching for a branch may take a while.</p>
<p>Another variant is by release target:</p>
<div class="highlight-python"><pre>project/ # Overall repository
+- trunk/ # Mainline development branch
+- releases/ # Container for release branches
| +- 0.8/ # The branch for release 0.8
| +- 0.9/ # The branch for release 0.9
+- 0.8/ # Container for branches targeting release 0.8
| +- feature1/ # Branch for "feature1" which is intended to be merged into 0.8
| +- feature2/ # Branch for "feature2" which is targeted for 0.8
+- 0.9/
+- feature3/ # Branch for "feature3", targeted for release 0.9</pre>
</div>
<p>Some possible variants include having the <tt class="docutils literal"><span class="pre">0.9</span></tt> directory imply
that it is branched <em>from</em> 0.9 rather than <em>for</em> 0.9, or having the <tt class="docutils literal"><span class="pre">0.8/release</span></tt>
as the official release 0.8 branch.</p>
<p>The general idea is that by targeting a release, you can look at what branches are
waiting to be merged. It doesn’t necessarily give you a good idea of what the
state of the branch (is it in development or finished awaiting review).
It also has a history-hiding effect, and otherwise has the same benefits
and deficits as a date-based sorting.</p>
</div>
<div class="section" id="simple-developer-naming-project-joe-foo-project-barry-bar">
<h2>Simple developer naming (<tt class="docutils literal"><span class="pre">project/joe/foo</span></tt>, <tt class="docutils literal"><span class="pre">project/barry/bar</span></tt>)<a class="headerlink" href="#simple-developer-naming-project-joe-foo-project-barry-bar" title="Permalink to this headline">¶</a></h2>
<p>Another possibly layout is to give each developer a directory, and then
have a single sub-directory for branches. Something like:</p>
<div class="highlight-python"><pre>project/ # Overall repository
+- trunk/ # Mainline branch
+- joe/ # A container for Joe's branches
| +- foo/ # Joe's "foo" branch of "project"
+- barry/
+- bar/ # Barry's "bar" branch of "project"</pre>
</div>
<p>The idea is that no branch is “nested” underneath another one, just that each developer
has his/her branches grouped together.</p>
<p>A variant which is used by <a class="reference external" href="https://launchpad.net">Launchpad</a> is:</p>
<div class="highlight-python"><pre>repository/
+- joe/ # Joe's branches
| +- project1/ # Container for Joe's branches of "project1"
| | +- foo/ # Joe's "foo" branch of "project1"
| +- project2/ # Container for Joe's "project2" branches
| +- bar/ # Joe's "bar" branch of "project2"
| ...
|
+- barry/
| +- project1/ # Container for Barry's branches of "project1"
| +- bug-10/ # Barry's "bug-10" branch of "project1"
| ...
+- group/
+- project1/
+- trunk/ # The main development focus for "project1"</pre>
</div>
<p>This lets you easily browse what each developer is working on. Focus branches
are kept in a “group” directory, which lets you see what branches the “group”
is working on.</p>
<p>This keeps different people’s work separated from each-other, but also makes it
hard to find “all branches for project X”. <a class="reference external" href="https://launchpad.net">Launchpad</a> compensates for this
by providing a nice web interface with a database back end, which allows a
“view” to be put on top of this layout.
This is closer to the model of people’s home pages, where each person has a
“<tt class="docutils literal"><span class="pre">~/public_html</span></tt>” directory where they can publish their own web-pages.
In general, though, when you are creating a shared repository for centralization
of a project, you don’t want to split it up by person and then project.
Usually you would want to split it up by project and then by person.</p>
</div>
<div class="section" id="summary">
<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
<p>In the end, no single naming scheme will work for everyone. It depends a lot on
the number of developers, how often you create a new branch, what sort of
lifecycles your branches go through. Some questions to ask yourself:</p>
<blockquote>
<div><ol class="arabic simple">
<li>Do you create a few long-lived branches, or do you create lots of “mini” feature branches
(Along with this is: Would you <em>like</em> to create lots of mini feature branches, but can’t
because they are a pain in your current VCS?)</li>
<li>Are you a single developer, or a large team?</li>
<li>If a team, do you plan on generally having everyone working on the same branch at the same
time? Or will you have a “stable” branch that people are expected to track.</li>
</ol>
</div></blockquote>
</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="#">Advanced shared repository layouts</a><ul>
<li><a class="reference internal" href="#svn-style-trunk-branches">“SVN-Style” (<tt class="docutils literal"><span class="pre">trunk/</span></tt>, <tt class="docutils literal"><span class="pre">branches/</span></tt>)</a><ul>
<li><a class="reference internal" href="#project-trunk"><tt class="docutils literal"><span class="pre">project/trunk</span></tt></a></li>
<li><a class="reference internal" href="#trunk-project"><tt class="docutils literal"><span class="pre">trunk/project</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#nested-style-project-branch-sub-branch">Nested Style (<tt class="docutils literal"><span class="pre">project/branch/sub-branch/</span></tt>)</a></li>
<li><a class="reference internal" href="#sorted-by-status-dev-merged-experimental">Sorted by Status (<tt class="docutils literal"><span class="pre">dev/</span></tt>, <tt class="docutils literal"><span class="pre">merged/</span></tt>, <tt class="docutils literal"><span class="pre">experimental/</span></tt>)</a></li>
<li><a class="reference internal" href="#sorted-by-date-release-etc-2006-06-2006-07-0-8-0-9">Sorted by date/release/etc (<tt class="docutils literal"><span class="pre">2006-06/</span></tt>, <tt class="docutils literal"><span class="pre">2006-07/</span></tt>, <tt class="docutils literal"><span class="pre">0.8/</span></tt>, <tt class="docutils literal"><span class="pre">0.9</span></tt>)</a></li>
<li><a class="reference internal" href="#simple-developer-naming-project-joe-foo-project-barry-bar">Simple developer naming (<tt class="docutils literal"><span class="pre">project/joe/foo</span></tt>, <tt class="docutils literal"><span class="pre">project/barry/bar</span></tt>)</a></li>
<li><a class="reference internal" href="#summary">Summary</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="organizing_your_workspace.html"
title="previous chapter">Organizing your workspace</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="setting_up_email.html"
title="next chapter">Configuring email</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/user-guide/shared_repository_layouts.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" size="18" />
<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="setting_up_email.html" title="Configuring email"
>next</a></li>
<li class="right" >
<a href="organizing_your_workspace.html" title="Organizing your workspace"
>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">Table of Contents (2.4.2)</a> »</li>
<li><a href="index.html" >Bazaar User Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
