<!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>Filtered views — 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="Bazaar User Guide" href="index.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">
<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><a href="../index.html">Table of Contents (2.6.0)</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="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 <tt class="docutils literal"><span class="pre">shelve</span></tt> and <tt class="docutils literal"><span class="pre">unshelve</span></tt> 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 <tt class="docutils literal"><span class="pre">view</span></tt>
command like this:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view file1 file2 dir1 ...
</pre></div>
</div>
<p>The output is:</p>
<div class="highlight-python"><div class="highlight"><pre>Using 'my' view: file1, file2, dir1
</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 <tt class="docutils literal"><span class="pre">view</span></tt> command without arguments:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view
</pre></div>
</div>
<p>If no view is current, a message will be output saying <tt class="docutils literal"><span class="pre">No</span> <span class="pre">current</span> <span class="pre">view.</span></tt>.
Otherwise the name and content of the current view will be displayed
like this:</p>
<div class="highlight-python"><div class="highlight"><pre>'my' view is: a, b, c
</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-python"><div class="highlight"><pre>bzr view --name view-name file1 dir1 ...
</pre></div>
</div>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --name doc NEWS doc/
Using doc view: NEWS, doc/
</pre></div>
</div>
<p>To list a named view:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --name view-name
</pre></div>
</div>
<p>To switch to a named view:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --switch view-name
</pre></div>
</div>
<p>To list all views defined:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --all
</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 <tt class="docutils literal"><span class="pre">off</span></tt>. 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-python"><div class="highlight"><pre>bzr view --switch off
</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-python"><div class="highlight"><pre>bzr view --switch my
</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-python"><div class="highlight"><pre>bzr view --delete
</pre></div>
</div>
<p>To delete a named view:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --name view-name --delete
</pre></div>
</div>
<p>To delete all views:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr view --delete --all
</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 <tt class="docutils literal"><span class="pre">doc/</span></tt> and <tt class="docutils literal"><span class="pre">doc/NEWS</span></tt> gets moved to <tt class="docutils literal"><span class="pre">NEWS</span></tt>,
the views stays defined as <tt class="docutils literal"><span class="pre">doc/</span></tt> and does not get changed
to <tt class="docutils literal"><span class="pre">doc/</span> <span class="pre">NEWS</span></tt>. 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">
<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>
<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 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="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><a href="../index.html">Table of Contents (2.6.0)</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-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
