<!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>Developer guide to bzrlib transports — 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="next" title="Interacting with the user" href="ui.html" />
<link rel="prev" title="Fetching data" href="fetch.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="ui.html" title="Interacting with the user"
accesskey="N">next</a></li>
<li class="right" >
<a href="fetch.html" title="Fetching data"
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">Developer Document Catalog (2.6.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="developer-guide-to-bzrlib-transports">
<h1>Developer guide to bzrlib transports<a class="headerlink" href="#developer-guide-to-bzrlib-transports" title="Permalink to this headline">¶</a></h1>
<p>This guide describes the <cite>Transport</cite> classes that Bazaar uses for most
local and remote file access. (Working tree files are the major
exception (<cite>bug 606249 <https://bugs.launchpad.net/bzr/+bug/606249></cite>).</p>
<div class="section" id="handling-symlinks">
<h2>Handling symlinks<a class="headerlink" href="#handling-symlinks" title="Permalink to this headline">¶</a></h2>
<p>A symlink creates an alias where files or directories can be accessed by a
different name. Symlinks are useful but raise a few annoying cases for
bzr.</p>
<p>It’s important to have tests for symlinks but these tests can’t run on
Windows, so you need eg</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">_test_needs_features</span> <span class="o">=</span> <span class="p">[</span><span class="n">tests</span><span class="o">.</span><span class="n">SymlinkFeature</span><span class="p">]</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-python"><div class="highlight"><pre><span class="bp">self</span><span class="o">.</span><span class="n">requireFeature</span><span class="p">(</span><span class="n">tests</span><span class="o">.</span><span class="n">SymlinkFeature</span><span class="p">)</span>
</pre></div>
</div>
<p>Bazaar versions symlinks as objects in their own right, whose content is
the path they point to. bzr doesn’t care whether a versioned
symlink is absolute or relative; or whether it points inside or outside
the working tree; or whether its referent exists or not. In Unix the
target of a symlink is a byte string; bzr treats this as a Unicode string
in the filesystem encoding (<cite>osutils._fs_enc</cite>).</p>
<p>So when we say <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">add</span> <span class="pre">symlink</span></tt>, this should always add the symlink to
its containing working tree, and never dereference the symlink.</p>
<p>However, <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">add</span> <span class="pre">symlink/file</span></tt> shouldn’t add <tt class="docutils literal"><span class="pre">file</span></tt> as a child of
<tt class="docutils literal"><span class="pre">symlink</span></tt>. (Symlinks don’t have files underneath them: they may point to
a directory which contains children, but if the symlink was pointed
somewhere else those children would be unaffected.) This could either add
the file in its containing working tree, or fail outright.</p>
<p>One interesting case for this is</p>
<div class="highlight-python"><div class="highlight"><pre>bzr add ~/dev/bug123/a.c
</pre></div>
</div>
<p>where <tt class="docutils literal"><span class="pre">~/dev</span></tt> is actually a symlink to <tt class="docutils literal"><span class="pre">/srv/dev/joe/</span></tt>. In this case
clearly the user does want us to follow the symlink to open the tree.</p>
<p>As of bzr2.2, when we open a <cite>WorkingTree</cite>, we typically immediately
compute its real path and store that as <tt class="docutils literal"><span class="pre">.basedir</span></tt>, but <cite>BzrDir</cite> stores
its apparent path. (This may not be the best thing.)</p>
<div class="section" id="useful-functions">
<h3>Useful functions<a class="headerlink" href="#useful-functions" title="Permalink to this headline">¶</a></h3>
<p><cite>bzrlib.osutils.dereference_path</cite> does the commonly useful operation of
resolving the directory part of a path, but leaving the filename
untouched. In other words</p>
<div class="highlight-python"><div class="highlight"><pre>ln -s x a
ln -s y x/b
dereference_path('a/b') => 'x/b'
</pre></div>
</div>
</div>
<div class="section" id="relative-paths-beyond-symlinks">
<h3>Relative paths beyond symlinks<a class="headerlink" href="#relative-paths-beyond-symlinks" title="Permalink to this headline">¶</a></h3>
<p>Another interesting case is when a control directory contains a relative
path, perhaps from a branch to its master or from a working tree to its
branch. If it contains <tt class="docutils literal"><span class="pre">../</span></tt> parts as it typically will, these may have
different effects depending on whether they’re looked up relative to the
real path or the apparent path given by the user. It may be that some
users expect different behaviours at different times.</p>
<p>Resolving the path relative to the real directory makes it somewhat more
consistent with what you would see by in a shell entering that directory
and then opening the given name. It may also make things more consistent
when there are multiple links to the same bzrdir. However it may cause
problems when using a transport that hides symlinks.</p>
<p>We could possibly handle this by doing less path arithmetic and asking the
OS or server to open the path including <tt class="docutils literal"><span class="pre">..</span></tt> and other relative
elements, but that might cause other problems. HTTP servers may do their
own path arithmetic before passing it to the OS.</p>
</div>
<div class="section" id="transports-that-hide-symlinks">
<h3>Transports that hide symlinks<a class="headerlink" href="#transports-that-hide-symlinks" title="Permalink to this headline">¶</a></h3>
<p>On local, SFTP and bzr+ssh transports, we can directly see symlinks as
symlinks. Over HTTP (and FTP?) they’re expanded by the server and we
cannot detect them. This can cause problems when bzr follows relative
paths because typically we will join the paths, and we may do this
inconsistently with how the server, which can see the symlinks, would do.</p>
</div>
<div class="section" id="symlinks-and-chroottransports">
<h3>Symlinks and ChrootTransports<a class="headerlink" href="#symlinks-and-chroottransports" title="Permalink to this headline">¶</a></h3>
<p>bzr has an internal concept of a <cite>ChrootTransport</cite> that locks access into
a particular directory. Symlinks should not break out of a chroot jail
which implies they should be expanded and checked within bzrlib.
(At least as long as the transport lets us see the symlink; otherwise it
may not be possible.)</p>
<blockquote>
<div></div></blockquote>
</div>
</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="#">Developer guide to bzrlib transports</a><ul>
<li><a class="reference internal" href="#handling-symlinks">Handling symlinks</a><ul>
<li><a class="reference internal" href="#useful-functions">Useful functions</a></li>
<li><a class="reference internal" href="#relative-paths-beyond-symlinks">Relative paths beyond symlinks</a></li>
<li><a class="reference internal" href="#transports-that-hide-symlinks">Transports that hide symlinks</a></li>
<li><a class="reference internal" href="#symlinks-and-chroottransports">Symlinks and ChrootTransports</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="fetch.html"
title="previous chapter">Fetching data</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ui.html"
title="next chapter">Interacting with the user</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/transports.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="ui.html" title="Interacting with the user"
>next</a></li>
<li class="right" >
<a href="fetch.html" title="Fetching data"
>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">Developer Document Catalog (2.6.0)</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>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-updates
>
by-pkgid
>
27647990744ebd9cfe32398f37f67e20
>
files
>
2650
