<!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>Filtered views — 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="Using stacked branches" href="stacked.html" />
<link rel="prev" title="Shelving Changes" href="shelving_changes.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="stacked.html" title="Using stacked branches"
accesskey="N">next</a></li>
<li class="right" >
<a href="shelving_changes.html" title="Shelving Changes"
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="filtered-views">
<h1>Filtered views<a class="headerlink" href="#filtered-views" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introducing-filtered-views">
<h2>Introducing filtered views<a class="headerlink" href="#introducing-filtered-views" title="Permalink to this headline">¶</a></h2>
<p>Views provide a mask over the tree so that users can focus on a subset
of a tree when doing their work. There are several cases where this
masking can be helpful. For example, technical writers and testers on
many large projects may prefer to deal with just the directories/files
in the project of interest to them.</p>
<p>Developers may also wish to break a large set of changes into multiple
commits by using views. While <code class="docutils literal notranslate"><span class="pre">shelve</span></code> and <code class="docutils literal notranslate"><span class="pre">unshelve</span></code> let developers
put some changes aside for a later commit, views let developers specify
what to include in (instead of exclude from) the next commit.</p>
<p>After creating a view, commands that support a list of files - status,
diff, commit, etc - effectively have that list of files implicitly
given each time. An explicit list of files can still be given to these
commands but the nominated files must be within the current view. In
contrast, tree-centric commands - pull, merge, update, etc. - continue
to operate on the whole tree but only report changes relevant to the
current view. In both cases, Bazaar notifies the user each time it uses
a view implicitly so that it is clear that the operation or output is
being masked accordingly.</p>
<p>Note: Filtered views are only supported in format 2a, the default in
Bazaar 2.0, or later.</p>
</div>
<div class="section" id="creating-a-view">
<h2>Creating a view<a class="headerlink" href="#creating-a-view" title="Permalink to this headline">¶</a></h2>
<p>This is done by specifying the files and directories using the <code class="docutils literal notranslate"><span class="pre">view</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">view</span> <span class="n">file1</span> <span class="n">file2</span> <span class="n">dir1</span> <span class="o">...</span>
</pre></div>
</div>
<p>The output is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Using</span> <span class="s1">'my'</span> <span class="n">view</span><span class="p">:</span> <span class="n">file1</span><span class="p">,</span> <span class="n">file2</span><span class="p">,</span> <span class="n">dir1</span>
</pre></div>
</div>
</div>
<div class="section" id="listing-the-current-view">
<h2>Listing the current view<a class="headerlink" href="#listing-the-current-view" title="Permalink to this headline">¶</a></h2>
<p>To see the current view, use the <code class="docutils literal notranslate"><span class="pre">view</span></code> command without arguments:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span>
</pre></div>
</div>
<p>If no view is current, a message will be output saying <code class="docutils literal notranslate"><span class="pre">No</span> <span class="pre">current</span> <span class="pre">view.</span></code>.
Otherwise the name and content of the current view will be displayed
like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s1">'my'</span> <span class="n">view</span> <span class="ow">is</span><span class="p">:</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span>
</pre></div>
</div>
</div>
<div class="section" id="switching-between-views">
<h2>Switching between views<a class="headerlink" href="#switching-between-views" title="Permalink to this headline">¶</a></h2>
<p>In most cases, a view has a short life-span: it is created to make a
selected change and is deleted once that change is committed. At other
times, you may wish to create one or more named views and switch
between them.</p>
<p>To define a named view and switch to it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">name</span> <span class="n">view</span><span class="o">-</span><span class="n">name</span> <span class="n">file1</span> <span class="n">dir1</span> <span class="o">...</span>
</pre></div>
</div>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">name</span> <span class="n">doc</span> <span class="n">NEWS</span> <span class="n">doc</span><span class="o">/</span>
<span class="n">Using</span> <span class="n">doc</span> <span class="n">view</span><span class="p">:</span> <span class="n">NEWS</span><span class="p">,</span> <span class="n">doc</span><span class="o">/</span>
</pre></div>
</div>
<p>To list a named view:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">name</span> <span class="n">view</span><span class="o">-</span><span class="n">name</span>
</pre></div>
</div>
<p>To switch to a named view:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">switch</span> <span class="n">view</span><span class="o">-</span><span class="n">name</span>
</pre></div>
</div>
<p>To list all views defined:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="nb">all</span>
</pre></div>
</div>
</div>
<div class="section" id="temporarily-disabling-a-view">
<h2>Temporarily disabling a view<a class="headerlink" href="#temporarily-disabling-a-view" title="Permalink to this headline">¶</a></h2>
<p>To disable the current view without deleting it, you can switch to the
pseudo view called <code class="docutils literal notranslate"><span class="pre">off</span></code>. This can be useful when you need to see the
whole tree for an operation or two (e.g. merge) but want to switch back
to your view after that.</p>
<p>To disable the current view without deleting it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">switch</span> <span class="n">off</span>
</pre></div>
</div>
<p>After doing the operations you need to, you can switch back to the
view you were using by name. For example, if the previous view used
the default name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">switch</span> <span class="n">my</span>
</pre></div>
</div>
</div>
<div class="section" id="deleting-views">
<h2>Deleting views<a class="headerlink" href="#deleting-views" title="Permalink to this headline">¶</a></h2>
<p>To delete the current view:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">delete</span>
</pre></div>
</div>
<p>To delete a named view:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">name</span> <span class="n">view</span><span class="o">-</span><span class="n">name</span> <span class="o">--</span><span class="n">delete</span>
</pre></div>
</div>
<p>To delete all views:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bzr</span> <span class="n">view</span> <span class="o">--</span><span class="n">delete</span> <span class="o">--</span><span class="nb">all</span>
</pre></div>
</div>
</div>
<div class="section" id="things-to-be-aware-of">
<h2>Things to be aware of<a class="headerlink" href="#things-to-be-aware-of" title="Permalink to this headline">¶</a></h2>
<p>Defining a view does not delete the other files in the working
tree - it merely provides a “lens” over the working tree.</p>
<p>Views are stored as working tree metadata. They are not
propagated by branch commands like pull, push and update.</p>
<p>Views are defined in terms of file paths. If you move a
file in a view to a location outside of the view, the view
will no longer track that path. For example, if a view is
defined as <code class="docutils literal notranslate"><span class="pre">doc/</span></code> and <code class="docutils literal notranslate"><span class="pre">doc/NEWS</span></code> gets moved to <code class="docutils literal notranslate"><span class="pre">NEWS</span></code>,
the views stays defined as <code class="docutils literal notranslate"><span class="pre">doc/</span></code> and does not get changed
to <code class="docutils literal notranslate"><span class="pre">doc/</span> <span class="pre">NEWS</span></code>. Likewise, deleting a file in a view does
not remove the file from that view.</p>
<p>The commands that use the current view are:</p>
<ul class="simple">
<li>status</li>
<li>diff</li>
<li>commit</li>
<li>add</li>
<li>remove</li>
<li>revert</li>
<li>mv</li>
<li>ls.</li>
</ul>
<p>Commands that operate on the full tree but only report changes
inside the current view are:</p>
<ul class="simple">
<li>pull</li>
<li>update</li>
<li>merge.</li>
</ul>
<p>Many commands currently ignore the current view. Over time,
some of these commands may be added to the lists above as
the need arises. By design, some commands will most likely
always ignore the current view because showing the whole
picture is the better thing to do. Commands in this group
include:</p>
<ul class="simple">
<li>log</li>
<li>info.</li>
</ul>
</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="#">Filtered views</a><ul>
<li><a class="reference internal" href="#introducing-filtered-views">Introducing filtered views</a></li>
<li><a class="reference internal" href="#creating-a-view">Creating a view</a></li>
<li><a class="reference internal" href="#listing-the-current-view">Listing the current view</a></li>
<li><a class="reference internal" href="#switching-between-views">Switching between views</a></li>
<li><a class="reference internal" href="#temporarily-disabling-a-view">Temporarily disabling a view</a></li>
<li><a class="reference internal" href="#deleting-views">Deleting views</a></li>
<li><a class="reference internal" href="#things-to-be-aware-of">Things to be aware of</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="shelving_changes.html"
title="previous chapter">Shelving Changes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="stacked.html"
title="next chapter">Using stacked branches</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/user-guide/filtered_views.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="stacked.html" title="Using stacked branches"
>next</a></li>
<li class="right" >
<a href="shelving_changes.html" title="Shelving Changes"
>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>
