<!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>Content Filters — 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 Reference" href="index.html" />
<link rel="next" title="Criss-Cross" href="criss-cross-help.html" />
<link rel="prev" title="Checkouts" href="checkouts-help.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="criss-cross-help.html" title="Criss-Cross"
accesskey="N">next</a></li>
<li class="right" >
<a href="checkouts-help.html" title="Checkouts"
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 Reference</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="content-filters">
<h1>Content Filters<a class="headerlink" href="#content-filters" title="Permalink to this headline">¶</a></h1>
<div class="section" id="content-formats">
<h2>Content formats<a class="headerlink" href="#content-formats" title="Permalink to this headline">¶</a></h2>
<p>Bazaar’s content filtering allows you to store files in a different
format from the copy in your working tree. This lets you, or your
co-developers, use Windows development tools that expect CRLF files
on projects that use other line-ending conventions. Among other things,
content filters also let Unix developers more easily work on projects
using Windows line-ending conventions, keyword expansion/compression,
and trailing spaces on lines in text files to be implicitly stripped
when committed.</p>
<p>To generalize, there are two content formats supported by Bazaar:</p>
<ul class="simple">
<li>a canonical format - how files are stored internally</li>
<li>a convenience format - how files are created in a working tree.</li>
</ul>
</div>
<div class="section" id="format-conversion">
<h2>Format conversion<a class="headerlink" href="#format-conversion" title="Permalink to this headline">¶</a></h2>
<p>The conversion between these formats is done by content filters.
A content filter has two parts:</p>
<ul class="simple">
<li>a read converter - converts from convenience to canonical format</li>
<li>a write converter - converts from canonical to convenience format.</li>
</ul>
<p>Many of these converters will provide <em>round-trip</em> conversion,
i.e. applying the read converter followed by the write converter
gives back the original content. However, others may provide an
asymmetric conversion. For example, a read converter might strip
trailing whitespace off lines in source code while the matching
write converter might pass content through unchanged.</p>
</div>
<div class="section" id="enabling-content-filters">
<h2>Enabling content filters<a class="headerlink" href="#enabling-content-filters" title="Permalink to this headline">¶</a></h2>
<p>Content filters are typically provided by plugins, so the first step
in using them is to install the relevant plugins and read their
documentation. Some plugins may be very specific about which files
they filter, e.g. only files ending in <tt class="docutils literal"><span class="pre">.java</span></tt> or <tt class="docutils literal"><span class="pre">.php</span></tt>.
In other cases, the plugin may leave it in the user’s hands to
define which files are to be filtered. This is typically done
using rule-based preferences. See <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">help</span> <span class="pre">rules</span></tt> for general
information about defining these.</p>
</div>
<div class="section" id="impact-on-commands">
<h2>Impact on commands<a class="headerlink" href="#impact-on-commands" title="Permalink to this headline">¶</a></h2>
<p>Read converters are only applied to commands that read content from
a working tree, e.g. status, diff and commit. For example, <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">diff</span></tt>
will apply read converters to files in the working tree, then compare
the results to the content last committed.</p>
<p>Write converters are only applied by commands that <strong>create files in a
working tree</strong>, e.g. branch, checkout, update. If you wish to see the
canonical format of a file or tree, use <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">cat</span></tt> or <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">export</span></tt>
respectively.</p>
<p>Note: <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">commit</span></tt> does not implicitly apply write converters after
comitting files. If this makes sense for a given plugin providing
a content filter, the plugin can usually achieve this effect by using a
<tt class="docutils literal"><span class="pre">start_commit</span></tt> or <tt class="docutils literal"><span class="pre">post_commit</span></tt> hook say. See <a class="reference internal" href="hooks-help.html"><em>Hooks</em></a>
for more information on hooks.</p>
</div>
<div class="section" id="refreshing-your-working-tree">
<h2>Refreshing your working tree<a class="headerlink" href="#refreshing-your-working-tree" title="Permalink to this headline">¶</a></h2>
<p>For performance reasons, Bazaar caches the timestamps of files in
a working tree, and assumes files are unchanged if their timestamps
match the cached values. As a consequence, there are times when
you may need to explicitly ask for content filtering to be reapplied
in one or both directions, e.g. after installing or reconfiguring
plugins providing it.</p>
<p>Here are some general guidelines for doing this:</p>
<blockquote>
<div><ul class="simple">
<li>To reapply read converters, <tt class="docutils literal"><span class="pre">touch</span></tt> files, i.e. update their
timestamp. Operations like <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">status</span></tt> should then reapply the
relevant read converters and compare the end result with the
canonical format.</li>
<li>To reapply write converters, ensure there are no local changes,
delete the relevant files and run <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">revert</span></tt> on those files.</li>
</ul>
</div></blockquote>
<p>Note: In the future, it is likely that additional options will be added
to commands to make this refreshing process faster and safer.</p>
</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="#">Content Filters</a><ul>
<li><a class="reference internal" href="#content-formats">Content formats</a></li>
<li><a class="reference internal" href="#format-conversion">Format conversion</a></li>
<li><a class="reference internal" href="#enabling-content-filters">Enabling content filters</a></li>
<li><a class="reference internal" href="#impact-on-commands">Impact on commands</a></li>
<li><a class="reference internal" href="#refreshing-your-working-tree">Refreshing your working tree</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="checkouts-help.html"
title="previous chapter">Checkouts</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="criss-cross-help.html"
title="next chapter">Criss-Cross</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/user-reference/content-filters-help.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="criss-cross-help.html" title="Criss-Cross"
>next</a></li>
<li class="right" >
<a href="checkouts-help.html" title="Checkouts"
>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 Reference</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>
