<!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>Simplifying Bazaar Configuration — 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="Bazaar Windows Shell Extension Options" href="tortoise-strategy.html" />
<link rel="prev" title="1 Bazaar Performance Roadmap" href="performance-roadmap.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="tortoise-strategy.html" title="Bazaar Windows Shell Extension Options"
accesskey="N">next</a></li>
<li class="right" >
<a href="performance-roadmap.html" title="1 Bazaar Performance Roadmap"
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">Developer Document Catalog (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="plans.html" accesskey="U">Plans</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="simplifying-bazaar-configuration">
<h1>Simplifying Bazaar Configuration<a class="headerlink" href="#simplifying-bazaar-configuration" title="Permalink to this headline">¶</a></h1>
<div class="section" id="goal">
<h2>Goal<a class="headerlink" href="#goal" title="Permalink to this headline">¶</a></h2>
<p>Not all needs can be addressed by the default values used inside bzr and
bzrlib, no matter how well they are chosen (and they are ;).</p>
<p>Options that are rarely used don’t deserve a corresponding command line
switch in one or several commands.</p>
<p>Many parts of <code class="docutils literal notranslate"><span class="pre">bzrlib</span></code> depends on some constants though and the user
should be able to customize the behavior to suit his needs so these
constants need to become configuration options or more generally, be easier
to set.</p>
<p>These options can be set from the command-line, acquired from an environment
variable or recorded in a configuration file.</p>
<p>To simplify writing (and reading), this document refers to the old and new
config designs:
* the old design is using <code class="docutils literal notranslate"><span class="pre">Config</span></code> as a base class for all config files,
* the new design use <code class="docutils literal notranslate"><span class="pre">ConfigStacks</span></code> of <code class="docutils literal notranslate"><span class="pre">Section</span></code> from config <code class="docutils literal notranslate"><span class="pre">Stores</span></code>.</p>
</div>
<div class="section" id="current-issues">
<h2>Current issues<a class="headerlink" href="#current-issues" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">Many parts of <code class="docutils literal notranslate"><span class="pre">bzrlib</span></code> declare constants and there is no way for the
user to look at or modify them (see <a class="reference external" href="http://pad.lv/832061">http://pad.lv/832061</a>).</p>
</li>
<li><p class="first">The old design requires a configuration object to create, modify or delete
a configuration option in a given configuration file. <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code>
makes it almost transparent for the user. Internally though, not all cases
are handled: only BranchConfig implements chained configs, nothing is
provided at the repository level and too many plugins define their own
section or even their own config file. (config.Stack now provides a way to
chain config files, BranchStack properly implements the desired behavior,
<code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code> uses the new design).</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> defines the options that need to override any setting
in <code class="docutils literal notranslate"><span class="pre">branch.conf</span></code> for both local and remotes branches (but some remote
branch options just ignore <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code>). Many users want a way to
define default values for options that are not defined in <code class="docutils literal notranslate"><span class="pre">branch.conf</span></code>
(and even more users think that <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> provide default values,
see also <a class="reference external" href="http://pad.lv/843211">http://pad.lv/843211</a> and <a class="reference external" href="http://pad.lv/832046">http://pad.lv/832046</a>). This could be
approximated today by <em>not</em> defining these options in <code class="docutils literal notranslate"><span class="pre">branch.conf</span></code> but
in <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> instead. This workaround doesn’t allow a user to
define defaults in <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> and override them in
<code class="docutils literal notranslate"><span class="pre">branch.conf</span></code>. (Allowing sections in ‘bazaar.conf’ (or introducing a new
defaults.conf’ allowing sections) can now address that. Defining and using
a new file is easier as it avoids handling a migration path for
bazaar.conf and doesn’t require banning the use of sections for special
purpose needs (ALIASES and BOOKMARKS for example)).</p>
</li>
<li><p class="first">Defining a new option requires adding a new method in the <code class="docutils literal notranslate"><span class="pre">Config</span></code>
object to get access to features like:</p>
<ul class="simple">
<li>should the option be inherited by more specific sections, (this was more
or less the default in the old design, it is addressed by section
matchers in the new one by letting users define options in whatever
relevant section and let the matcher select the right ones).</li>
<li>should the inherited value append the relative path between the section
one and the location it applies to (see <a class="reference external" href="http://pad.lv/832013">http://pad.lv/832013</a>, fixed),</li>
<li>the default value (including calling any python code that may be
required to calculate this value)(see <a class="reference external" href="http://pad.lv/832064">http://pad.lv/832064</a>, fixed),</li>
<li>priority between sections in various config files (this is defined by
the section matcher associated with a given config store for stacks,
<a class="reference external" href="http://pad.lv/832046">http://pad.lv/832046</a> is about adding a section matcher with clearer
semantics than the one used for locations.conf).</li>
</ul>
<p>A related problem is that, in the actual implementation, some
configuration options have defined methods, others don’t and this is
inconsistent. (Using only Stacks addresses that).</p>
</li>
<li><p class="first">Access to the ‘active’ configuration option value from the command line
doesn’t give access to the specific section. This is a concern if the user
has no other way to address a specific configuration option including
Store and Section when using <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code> (see
<a class="reference external" href="http://pad.lv/725234">http://pad.lv/725234</a>). Plugins defining their own stacks and/or stores
also have no way to properly plug into <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code> (see
<a class="reference external" href="http://pad.lv/788991">http://pad.lv/788991</a>).</p>
</li>
<li><p class="first">Rules for configuration options are not clearly defined for remote
branches (they may differ between dumb and smart servers the former will
use the local <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code> and <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> files while the later
will use (or ignore ?) the remote ones).</p>
</li>
<li><p class="first">The features offered by the Bazaar configuration files should be easily
accessible to plugin authors either by supporting plugin configuration
options in the configuration files or allowing the plugins to define their
own configuration files. (Separating Section, Store and Stack starts
addressing that, a stack registry should complete the needed means
<a class="reference external" href="http://pad.lv/832036">http://pad.lv/832036</a>).</p>
</li>
<li><p class="first">While the actual configuration files support sections, they are used in
mutually exclusive ways that make it impossible to offer the same set of
features to all configuration files:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code> use arbitrary names for sections. <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> is used
for global options, <code class="docutils literal notranslate"><span class="pre">ALIASES</span></code> are used to define command aliases,
plugins can define their own sections, some plugins do that
(<code class="docutils literal notranslate"><span class="pre">bzr-bookmarks</span></code> use <code class="docutils literal notranslate"><span class="pre">BOOKMARKS</span></code> for example), some other define
their own sections (this is addressed with the new design by using only
the <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> section and ignore the others. When needed, one can
create a specific stack to get access to a specific section).</li>
<li><code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> use globs as section names. This provides an easy
way to associate a set of options to a matching working tree or
branch, including remote ones.</li>
<li><code class="docutils literal notranslate"><span class="pre">branch.conf</span></code> doesn’t use any section.</li>
</ul>
<p>This is addressed by defining different stacks selecting the relevant
sections from the stores involved. <code class="docutils literal notranslate"><span class="pre">ALIASES</span></code> for example can define a
stack that select only the <code class="docutils literal notranslate"><span class="pre">ALIASES</span></code> section from <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code>.</p>
</li>
<li><p class="first">There is no easy way to get configuration options for a given repository
or an arbitrary path. Working trees and branches are generally organized
in hierarchies and being able to share the option definitions is an often
required feature. This can also address some needs exhibited by various
branch schemes like looms, pipeline, colocated branches and nested
trees. Being able to specify options <em>in</em> a working tree could also help
support conflict resolution options for a given file, directory or
subtree (see <a class="reference external" href="http://pad.lv/359320">http://pad.lv/359320</a>).</p>
</li>
<li><p class="first">Since sections allow different definitions for the same option (in the
same store), a total order should be defined between sections to select
the right definition for a given context (paths or globs for
<code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> but other schemes can be used, window names for qbzr,
repository UUIDs for bzr-svn for example). Allowing globs for section
names is harmful in this respect since the order is currently defined as
being based on the number of path components. The caveat here is that if
the order is always defined for a given set of sections it can change when
one or several globs are modified and the user may get surprising and
unwanted results in these cases. The lexicographical order is otherwise
fine to define what section is more specific than another. (This may not
be a problem in real life since longer globs are generally more specific
than shorter ones and explicit paths should also be longer than matching
globs. That may leave a glob and a path of equal length in a gray area but
in practice using <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code> should give enough feedback to address
them. See also <a class="reference external" href="http://pad.lv/832046">http://pad.lv/832046</a> asking for a less magical section
matcher).</p>
</li>
<li><p class="first">Internally, configuration files (and their fallbacks, <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code> and
<code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> for <code class="docutils literal notranslate"><span class="pre">branch.conf</span></code>) are read every time <em>one</em> option is
queried. Likewise, setting or deleting a configuration option implies
writing the configuration file <em>immediately</em> after re-reading the file to
avoid racing updates (see <a class="reference external" href="http://pad.lv/832042">http://pad.lv/832042</a>).</p>
</li>
<li><p class="first">The current implementation use a mix of transport-based and direct file
systems operations (Addressed by Store implementation relying on
transports only and the hpss implementing the corresponding verbs).</p>
</li>
<li><p class="first">While the underlying <code class="docutils literal notranslate"><span class="pre">ConfigObj</span></code> implementation provides an
interpolation feature, the <code class="docutils literal notranslate"><span class="pre">bzrlib</span></code> implementation doesn’t provide an
easy handling of templates where other configuration options can be
interpolated. Instead, <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> (and only it) allows for
<code class="docutils literal notranslate"><span class="pre">appendpath</span></code> and <code class="docutils literal notranslate"><span class="pre">norecurse</span></code>. (Cross-section, cross-file interpolation
and section local options are now implemented in the new design).</p>
</li>
<li><p class="first">Inherited list values can’t be modified, a more specific configuration can
only redefine the whole list.</p>
</li>
<li><p class="first">There is no easy way to define dicts (the most obvious one being to use a
dedicated section which is already overloaded). Using embedded sections
for this would not be practical either if we keep using a no-name section
for default values. In a few known cases, a bencoded dict is stored in a
config value, so while this isn’t user-friendly, not providing a better
alternative shouldn’t be a concern. A possible, limited, implementation
can be envisioned: limiting the dict to a single level only, with simple
names as keys and unicode strings as values. The keys can then be mapped
to options prefixed with the dict name.</p>
</li>
</ul>
</div>
<div class="section" id="proposed-implementation">
<h2>Proposed implementation<a class="headerlink" href="#proposed-implementation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="configuration-files-definition">
<h3>Configuration files definition<a class="headerlink" href="#configuration-files-definition" title="Permalink to this headline">¶</a></h3>
<p>While of course configurations files can be versioned they are not intended
to be accessed in sync with the files they refer to (one can imagine
handling versioned properties this way but this is <em>not</em> what the bazaar
configuration files are targeted at). <code class="docutils literal notranslate"><span class="pre">bzr</span></code> will always refer to
configuration files as they exist on disk when an option is queried or set.</p>
<p>The configuration files are generally local to the file system but some of
them can be accessed remotely (<code class="docutils literal notranslate"><span class="pre">branch.conf</span></code>, <code class="docutils literal notranslate"><span class="pre">repo.conf</span></code>).</p>
</div>
<div class="section" id="naming">
<h3>Naming<a class="headerlink" href="#naming" title="Permalink to this headline">¶</a></h3>
<p>Option names are organized into a name space for a given stack. One such set
includes <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code>, <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code>, <code class="docutils literal notranslate"><span class="pre">branch.conf</span></code>, etc. Plugins
can define their own sets for their own needs. While it is conceivable that
the same option name can be used in unrelated configuration stacks, it seems
better to define a single name space for all options if only to avoid
ambiguities.</p>
<p>Using a name space is meant to help:</p>
<ul class="simple">
<li>avoid collisions between bzr and plugins and between plugins,</li>
<li>discover the available options and making them easier to remember,</li>
<li>organise the documentation for the option set.</li>
</ul>
<p>Using valid python identifiers is recommended but not enforced (but we may
do so in the future).</p>
<p>The option name space is organized by topic:</p>
<ul class="simple">
<li>bzrlib options are grouped by topic (<code class="docutils literal notranslate"><span class="pre">branch</span></code>, <code class="docutils literal notranslate"><span class="pre">tree</span></code>, <code class="docutils literal notranslate"><span class="pre">repo</span></code>)</li>
<li>plugins are encouraged (but not required) to prefix their specific options
with their name (<code class="docutils literal notranslate"><span class="pre">qbzr.</span></code> for qbzr)</li>
<li>collisions are detected at registration time so users are protected from
incompatibilities between plugins,</li>
<li>options that need to be used by several plugins (or shared between <code class="docutils literal notranslate"><span class="pre">bzr</span></code>
core and plugins) should be discussed but these discussions are already
happening so the risk of misuse is low enough.</li>
</ul>
</div>
<div class="section" id="value">
<h3>Value<a class="headerlink" href="#value" title="Permalink to this headline">¶</a></h3>
<p>All option values are text. They are provided as Unicode strings to API
users with some refinements:</p>
<ul class="simple">
<li>boolean values can be obtained for a set of acceptable strings (yes/no,
y/n, on/off, etc), (implemented with the <code class="docutils literal notranslate"><span class="pre">from_unicode</span></code> parameter)</li>
<li>a list of strings from a value containing a comma separated list of
strings.</li>
</ul>
<p>Since the configuration files can be edited by the user, <code class="docutils literal notranslate"><span class="pre">bzr</span></code> doesn’t
expect their content to be valid at all times. Instead, the code using
options should be ready to handle <em>invalid</em> values by warning the user and
falling back to a default value.</p>
<p>Likely, if an option is not defined in any configuration file, the code
should fallback to a default value (helpers should be provided by the API to
handle common cases: warning the user, getting a particular type of value,
returning a default value)(most of that is now handled at Option definition).</p>
<p>This also ensures compatibility with values provided via environment
variables or from the command line (where no validation can be expected
either)(done in the new design).</p>
</div>
<div class="section" id="option-expansion">
<h3>Option expansion<a class="headerlink" href="#option-expansion" title="Permalink to this headline">¶</a></h3>
<p>Some option values can be templates and contain references to other
options. This is especially useful to define URLs in sections shared for
multiple branches for example. It can also be used to describe commands
where some parameters are set by <code class="docutils literal notranslate"><span class="pre">bzrlib</span></code> at runtime.</p>
<p>Since option values are text-only, and to avoid clashing with other option
expansion (also known as interpolation) syntaxes, references are enclosed
with curly brackets:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">push_location</span> <span class="o">=</span> <span class="n">lp</span><span class="p">:</span><span class="o">~</span><span class="p">{</span><span class="n">launchpad_username</span><span class="p">}</span><span class="o">/</span><span class="n">bzr</span><span class="o">/</span><span class="p">{</span><span class="n">nick</span><span class="p">}</span>
</pre></div>
</div>
<p>In the example above, <code class="docutils literal notranslate"><span class="pre">launchpad_username</span></code> is an already defined
configuration option while <code class="docutils literal notranslate"><span class="pre">nick</span></code> is the branch nickname and is set when a
configuration applies to a given branch.</p>
<p>The interpolation implementation should accept an additional dict so that
<code class="docutils literal notranslate"><span class="pre">bzrlib</span></code> or plugins can define references that can be expanded without
being existing configuration options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">diff_command</span><span class="o">=</span><span class="p">{</span><span class="n">cmd</span><span class="p">}</span> <span class="p">{</span><span class="n">cmd_opts</span><span class="p">}</span> <span class="p">{</span><span class="n">file_a</span><span class="p">}</span> <span class="p">{</span><span class="n">file_b</span><span class="p">}</span>
</pre></div>
</div>
<p>There are two common errors that should be handled when handling interpolation:</p>
<ul class="simple">
<li>loops: when a configuration value refers to itself, directly or indirectly,</li>
<li>undefined references: when a configuration value refers to an unknown option.</li>
</ul>
<p>The loop handling can be modified to allow cross-sections and cross-files
interpolation: if an option refers to itself (directly or indirectly) during
an expansion, the fallback sections or files can be queried for its value.</p>
<p>This allows list values to refer to the definition in the less specific
configurations:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>bazaar.conf:
debug_flags = hpss
branch.conf for mybranch:
debug_flags = {debug_flags}, hpssdetail
$ bzr -d mybranch config debug_flags
hpss, hpssdetail
</pre></div>
</div>
<p>Undefined references are detected if they are not defined in any
configuration. This will trigger errors while displaying the value. Diagnosing
typos should be doable in this case.</p>
</div>
<div class="section" id="configuration-file-syntax">
<h3>Configuration file syntax<a class="headerlink" href="#configuration-file-syntax" title="Permalink to this headline">¶</a></h3>
<p>The configuration file is mostly an <code class="docutils literal notranslate"><span class="pre">ini-file</span></code>. It contains <code class="docutils literal notranslate"><span class="pre">name</span> <span class="pre">=</span> <span class="pre">value</span></code>
lines grouped in sections. A section starts with a string enclosed in squared
brackets (‘[section_name]`), this string uniquely identifies the section in
the file. Comments are allowed by prefixing them with the ‘#’ character.</p>
<p>A section is named by the path (or some other unuique identifier) it should
apply to (more examples below).</p>
<p>When sections are used, they provide a finer grain of configuration by
defining option sets that apply to some working trees, branches,
repositories (or any kind of context) or part of them. The relationship
between a given context and the sections it applies to is defined by the
config file.</p>
<p>So far, Bazaar uses a glob in <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> and select the sections
that apply to a given url (or a local path).</p>
<p>The subset is defined by the common leading path or a glob.</p>
<p>Different kinds of section names can be defined:</p>
<ul class="simple">
<li>a full url: used to described options for remote branches and
repositories (LocationMatcher supports this).</li>
<li>local absolute path: used for working trees, branches or repositories
on the local disks (LocationMatcher supports this).</li>
<li>relative path: the path is relative to the configuration file and can be
used for colocated branches or threads in a loom, i.e any working tree,
branch or repository that is located in a place related to the
configuration file path. Some configuration files may define this path
relationship in specific ways to make them easier to use (i.e. if a config
file is somewhere below <code class="docutils literal notranslate"><span class="pre">.bzr</span></code> and refers to threads in a loom for
example, the relative path would be the thread name, it doesn’t have to be
an <em>exact</em> relative path, as long as its interpretation is unambiguous and
clear for the user) (No section matchers support this so far, needs to
file a bug)</li>
</ul>
</div>
<div class="section" id="section-matching">
<h3>Section matching<a class="headerlink" href="#section-matching" title="Permalink to this headline">¶</a></h3>
<p>Section names define another name space (than the option names one) with an
entirely different purpose: in a given configuration file, for a given
context, only some sections will be relevant and will be queried in a
specific order.</p>
<p>This matching is specific to each config file and implemented by the
SectionMatcher objects.</p>
<p>Whatever this matching does, the user can observe the results with the <code class="docutils literal notranslate"><span class="pre">bzr</span>
<span class="pre">config</span></code> command which displays the sections in the order they are queried.</p>
<div class="section" id="locationmatcher">
<h4>LocationMatcher<a class="headerlink" href="#locationmatcher" title="Permalink to this headline">¶</a></h4>
<p>The context here is either:</p>
<ul class="simple">
<li>an URL,</li>
<li>a local path.</li>
</ul>
<p>Note that for both the provided context and the section names, if an URL uses
a <code class="docutils literal notranslate"><span class="pre">file:///</span></code> form, it is converted to a local path.</p>
<p>The sections names can use globs for each path component
(i.e. <code class="docutils literal notranslate"><span class="pre">/dir/*/subdir</span></code> is allowed but <code class="docutils literal notranslate"><span class="pre">/dir/\*\*/subdir</span></code> will match
<code class="docutils literal notranslate"><span class="pre">/dir/a/subdir</span></code> but not <code class="docutils literal notranslate"><span class="pre">/dir/a/b/subdir</span></code>.</p>
<p>The reason is that the ordering is defined by sorting the section names
matching the context on the number of path components followed by the path
itself in lexicographical order. This results in most specific sections being
queried before the more generic ones.</p>
</div>
<div class="section" id="pathmatcher">
<h4>PathMatcher<a class="headerlink" href="#pathmatcher" title="Permalink to this headline">¶</a></h4>
<p><code class="docutils literal notranslate"><span class="pre">LocationMatcher</span></code> has some obscure (for unaware users) edge cases and
limitations that can be surprising. <code class="docutils literal notranslate"><span class="pre">PathMatcher</span></code> aims at addressing these
issues by providing simpler rules while still giving full control to the
user (<a class="reference external" href="http://pad.lv/832046">http://pad.lv/832046</a>).</p>
<p>The context here is a local path, absolute or relative. If the path is
relative it is interpreted from the file base directory.</p>
<p>Note that ‘base directory’ for configuration files in Bazaar directories is
really:</p>
<ul class="simple">
<li>the home directory for files under <code class="docutils literal notranslate"><span class="pre">~/.bazaar</span></code>,</li>
<li>the <code class="docutils literal notranslate"><span class="pre">.bzr</span></code> base directory for files under <code class="docutils literal notranslate"><span class="pre">.bzr</span></code>.</li>
</ul>
<p>The order is the one observed in the file so most generic values are specified
first and most specific ones last. As such, the order in the file is the
opposite of the one displayed by <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">config</span></code> which displays most specific
values first. This seems to be the most natural order in both cases.</p>
<p>A section matches if the section name is a prefix of the context path
(relative paths being converted to absolute on the fly).</p>
</div>
</div>
<div class="section" id="the-option-object">
<h3>The Option object<a class="headerlink" href="#the-option-object" title="Permalink to this headline">¶</a></h3>
<p>(copied from a recent version of bzr.dev for easier reading, refer to the
original for an up to date version)</p>
<p>The Option object is used to define its properties:</p>
<ul class="simple">
<li>name: a name: a valid python identifier (even if it’s not used as an
identifier in python itself). This is also used to register the option.</li>
<li>default: the default value that Stack.get() should return if no
value can be found for the option.</li>
<li>default_from_env: a list of environment variables. The first variable set
will provide a default value overriding ‘default’ which remains the
default value if <em>no</em> environment variable is set.</li>
<li>help: a doc string describing the option, the first line should be a
summary and can be followed by a blank line and a more detailed
explanation.</li>
<li>from_unicode: a callable accepting a unicode string and returning a
suitable value for the option. If the string cannot be coerced it should
return None.</li>
<li>invalid: the action to be taken when an invalid value is encountered in a
store (during a Stack.get()).</li>
</ul>
</div>
<div class="section" id="the-section-object">
<h3>The Section object<a class="headerlink" href="#the-section-object" title="Permalink to this headline">¶</a></h3>
<p>Options are grouped into sections which share some properties with the well
known dict objects:</p>
<ul class="simple">
<li>the key is the name,</li>
<li>you can get, set and remove an option,</li>
<li>the value is a unicode string.</li>
</ul>
<p>MutableSection is needed to set or remove an option, ReadOnlySection should
be used otherwise.</p>
</div>
<div class="section" id="the-store-object">
<h3>The Store object<a class="headerlink" href="#the-store-object" title="Permalink to this headline">¶</a></h3>
<p>This is an implementation-level object that should rarely be used directly.</p>
<ul>
<li><p class="first">it can be local or remote</p>
</li>
<li><p class="first">locking</p>
<p>All lock operations should be implemented via transport objects. (True for
Store).</p>
</li>
<li><p class="first">option life cycle</p>
<p>Working trees, branches and repositories should define a config attribute
following the same life cycle as their lock: the associated config file is
read once and written once if needed. This should minimize the file system
accesses or the network requests. There is no known racing scenarios for
configuration options, changing the existing implementation to this less
constrained one shouldn’t introduce any. Yet, in order to detect such
racing scenarios, we can add a check that the current content of the
configuration file is the expected one before writing the new content and
emit warnings if differences occur. The checks should be performed for the
modified values only. As of today (and in the foreseeable future), the
size of the configuration files are small enough to be kept in memory (see
<a class="reference external" href="http://pad.lv/832042">http://pad.lv/832042</a>).</p>
</li>
</ul>
</div>
<div class="section" id="the-stack-object">
<h3>The Stack object<a class="headerlink" href="#the-stack-object" title="Permalink to this headline">¶</a></h3>
<p>This the object that provides access to the needed features:</p>
<ul class="simple">
<li>getting an option value,</li>
<li>setting an option value,</li>
<li>deleting an option value,</li>
<li>handling a list of configuration files and for each of them a section
matcher providing the sections that should be tried in the given order to
find an option.</li>
<li>handling a Store and a section where option creation, modification and
deletion will occur.</li>
</ul>
<p>Depending on the files involved, a working tree, branch or repository object
(or more generally a context) should be provided to access the corresponding
configuration files. Note that providing a working tree object also
implicitly provides the associated branch and repository object so only one
of them is required (or none for configuration files specific to the user
like <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code>).</p>
<div class="section" id="getting-an-option-value">
<h4>Getting an option value<a class="headerlink" href="#getting-an-option-value" title="Permalink to this headline">¶</a></h4>
<p>Depending on the option, there are various places where it can be defined
and several ways to override these settings when needed.</p>
<p>The following lists all possible places where a configuration option can
be defined, but some options will make sense in only some of them. The
first to define a value for an option wins (None is therefore used to
express that an option is not set).</p>
<ul>
<li><p class="first">command-line
<code class="docutils literal notranslate"><span class="pre">-Ooption=value</span></code> see <a class="reference external" href="http://pad.lv/491196">http://pad.lv/491196</a>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">~/.bazaar/locations.conf</span></code></p>
<p>When an option is set in <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> it overrides any other
configuration file. This should be used with care as it allows setting a
different value than what is recommended by the project</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">tree</span></code> (Not Implemented Yet)</p>
<p>The options related to the working tree.</p>
<p>This includes all options related to commits, ignored files, junk files,
etc.</p>
<p>Note that the sections defined there can use relative paths if some
options should apply to a subtree or some specific files only.</p>
<p>See <a class="reference external" href="http://pad.lv/430538">http://pad.lv/430538</a> and <a class="reference external" href="http://pad.lv/654998">http://pad.lv/654998</a>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">branch</span></code> located in <code class="docutils literal notranslate"><span class="pre">.bzr/branch/branch.conf</span></code></p>
<p>The options related to the branch.</p>
<p>Sections can be defined for colocated branches or loom threads.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">repository</span></code> (Not Implemented Yet)</p>
<p>The options related to the repository.</p>
<p>Using an option to describe whether or not a repository is shared could
help address <a class="reference external" href="http://pad.lv/342119">http://pad.lv/342119</a> but this will probably requires a format
bump).</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">project</span></code> (Not Implemented Yet)</p>
<p>The options common to all branches and working trees for a project.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">organization</span></code> (Not Implemented Yet)</p>
<p>The options common to all branches and working trees for an organization.</p>
<p>See <a class="reference external" href="http://pad.lv/419854">http://pad.lv/419854</a>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">system</span></code> (Not Implemented Yet but see <a class="reference external" href="http://pad.lv/419854">http://pad.lv/419854</a> and
<a class="reference external" href="https://code.launchpad.net/~thomir/bzr/add-global-config/+merge/69592">https://code.launchpad.net/~thomir/bzr/add-global-config/+merge/69592</a>)</p>
<p>The options common to all users of a system (may be /etc/bzr/defaults
or /usr/local/etc/bzr/defaults or
/Library/Preferences/com.canonical.defaults or c:windowsbazaar.conf
(someone fix this one please ;) depending on the OS).</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code></p>
<p>The options the user has selected for the host he is using.</p>
<p>Sections can be defined for both remote and local branches to define
default values (i.e. the most common use of <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> today).</p>
</li>
<li><p class="first">default (implemented by the OptionRegistry)</p>
<p>The options defined in the <code class="docutils literal notranslate"><span class="pre">bzr</span></code> source code.</p>
<p>This will be implemented via the Option objects.</p>
</li>
</ul>
<p>Plugins can define additional configuration files as they see fit and
insert them in this list, see their documentation for details.</p>
</div>
</div>
</div>
<div class="section" id="compatibility">
<h2>Compatibility<a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h2>
<p>There are ways to keep the same files while ensuring compatibility via various
tricks but there are cases where using new files to replace the old ones is
definitely easier:</p>
<ul class="simple">
<li>no need to ensure that the new files are correctly handled by old bzr
versions,</li>
<li>making it clear for users that there is a switch and let them migrate at
their own pace.</li>
</ul>
<p>The known cases so far are described below.</p>
<p>Obvious at this point:</p>
<ul class="simple">
<li>Branch provides <code class="docutils literal notranslate"><span class="pre">get_config</span></code> for the old design and <code class="docutils literal notranslate"><span class="pre">get_config_stack</span></code>
for the new design so that both designs are supported. Once the store
sharing is implemented, we may want to use an attribute for the stack and
deprecate both <code class="docutils literal notranslate"><span class="pre">get_config</span></code> and <code class="docutils literal notranslate"><span class="pre">get_config_stack</span></code>.</li>
<li>Sections names in <code class="docutils literal notranslate"><span class="pre">bazaar.conf</span></code> are arbitrary (except <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code>) so
it’s easier to leave the file untouched and let plugin authors and users
migrate away (or not) from them. For <code class="docutils literal notranslate"><span class="pre">bzr</span></code> itself, that means
<code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> is the only section used for most of the options and provides
user defaults. <code class="docutils literal notranslate"><span class="pre">ALIASES</span></code> requires a specific stack but only the <code class="docutils literal notranslate"><span class="pre">bzr</span>
<span class="pre">alias</span></code> command cares about that.</li>
<li>Option policies should be deprecated:<ul>
<li>The <code class="docutils literal notranslate"><span class="pre">norecurse</span></code> policy is useless, all options are recursive by
default. If specific values are needed for specific paths, they can just
be defined as such (in the appropriate sections or files).</li>
<li>The <code class="docutils literal notranslate"><span class="pre">appendpath</span></code> policy should be implemented via interpolation and a
<code class="docutils literal notranslate"><span class="pre">relpath</span></code> option provided by the configuration framework
(<a class="reference external" href="http://pad.lv/832013">http://pad.lv/832013</a>).</li>
</ul>
</li>
<li>Section order in <code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> has issues which make a migration to a
different way to organize the sections (hence the file content) far easier
with a new file.</li>
<li><code class="docutils literal notranslate"><span class="pre">locations.conf</span></code> is really for overrides but many users have been using it
to provide defaults. There is no way to know if the whole content has been
used for defaults or overrides or a mix of both. So there is no way to
migrate this automatically.</li>
</ul>
<p>Unclear at this point:</p>
<ul>
<li><p class="first">[BOOKMARKS] section can be replaced by <code class="docutils literal notranslate"><span class="pre">bookmarks.xxx</span></code> options (the
bookmarks plugins already uses <code class="docutils literal notranslate"><span class="pre">bookmarks_xxx</span></code> in branch.conf since no
sections were supported there). The easiest here is probably to just merge
the plugin into core and use the appropriate option names consistently. A
<code class="docutils literal notranslate"><span class="pre">config:</span></code> directory service may even be better as any option can be used
as a bookmark. This allows things like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">/</span><span class="n">whatever</span><span class="o">/</span><span class="n">path</span><span class="p">]</span>
<span class="n">my_push</span> <span class="o">=</span> <span class="n">lp</span><span class="p">:</span><span class="o"><</span><span class="n">launchpad</span><span class="o">.</span><span class="n">login</span><span class="o">>/</span><span class="n">xxx</span><span class="o">/</span><span class="p">{</span><span class="n">nick</span><span class="p">}</span>
<span class="n">web_site</span><span class="o">=</span><span class="n">ftp</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span>
<span class="n">bzr</span> <span class="n">push</span> <span class="n">config</span><span class="p">:</span><span class="n">web_site</span>
</pre></div>
</div>
<p>Which means we completely replace the plugin and don’t need to care about
migrating the section.</p>
</li>
<li><p class="first">[ALIASES] section can be replaced by corresponding bzr.alias.xxx
options. This could be automated by creating the corresponding options ?</p>
</li>
<li><p class="first">I don’t know about other sections, feedback welcome. Plugin authors are
encouraged to migrate to the new name space scheme by prefixing their
options with their plugin name.</p>
</li>
</ul>
</div>
<div class="section" id="notes">
<h2>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h2>
<p>These are random notes about concepts, ideas or issues not implemented yet.</p>
<div class="section" id="developer-facing-concepts">
<h3>Developer facing concepts<a class="headerlink" href="#developer-facing-concepts" title="Permalink to this headline">¶</a></h3>
<div class="section" id="option">
<h4>Option<a class="headerlink" href="#option" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>list of allowed Config IDs (this allows a list of possible config files in
bazaar.conf only option and use it while bootstrapping the config
creations).</li>
<li>blacklist of config IDs (some options <em>can’t</em> be stored (modified) by the
user)</li>
</ul>
<p>An alternative is to just let the devs decide which stack they use for a
given option, <code class="docutils literal notranslate"><span class="pre">stacked_on_location</span></code> for example is said to relate to the
branch only and changing it or setting it in a different config file may not
be appropriate. This may not be a good example as there is also the
<code class="docutils literal notranslate"><span class="pre">default_stack_on</span></code> option which can be set only in <code class="docutils literal notranslate"><span class="pre">control.conf</span></code>
though…</p>
</div>
<div class="section" id="stack">
<h4>Stack<a class="headerlink" href="#stack" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>a lazy cache for the option values (should be reset on modifications as
interpolations will make it tricky to update incrementally) (see FIXME in
config.py Stack.get()))</li>
<li>ensures that the Stores involved generate as less IOs as possible (see
<a class="reference external" href="http://pad.lv/832042">http://pad.lv/832042</a>)</li>
<li>ensures that the transaction is the object life time (i.e. modifications
will be taken into account <em>iff</em> they are committed explicitly).</li>
</ul>
</div>
<div class="section" id="stackregistry">
<h4>StackRegistry<a class="headerlink" href="#stackregistry" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>ensures that a config ID is a unique identifier</li>
<li>register Stacks</li>
</ul>
</div>
<div class="section" id="store">
<h4>Store<a class="headerlink" href="#store" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>ensures that the transaction is the object life time (i.e. modifications
will be taken into account <em>iff</em> they are committed explicitly).</li>
</ul>
</div>
</div>
<div class="section" id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<div class="section" id="store-examples">
<h4>store examples:<a class="headerlink" href="#store-examples" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>ConfigObj (bazaar.conf)</li>
<li>DB (<scheme>://bazaar.launchpad.net/bazaar.conf)</li>
</ul>
</div>
</div>
<div class="section" id="why-and-when-locking-config-files-matter">
<h3>Why and when locking config files matter<a class="headerlink" href="#why-and-when-locking-config-files-matter" title="Permalink to this headline">¶</a></h3>
<p>This is relevant for <a class="reference external" href="http://pad.lv/832042">http://pad.lv/832042</a>.</p>
<p><code class="docutils literal notranslate"><span class="pre">bzr</span></code> behavior, as well as the objects it acts upon, is configured via a
set of so-called configuration files.</p>
<p>These files allow to define working trees, branches and repositories, their
relationships and how <code class="docutils literal notranslate"><span class="pre">bzr</span></code> should handle them.</p>
<p>The default behavior of <code class="docutils literal notranslate"><span class="pre">bzr</span></code> is aimed at making this configuration as
transparent as possible by keeping track of how these objects are created
and modified when they are used. In short, they are useless until you want
to change the default behavior in some specific context.</p>
<p>We mostly <strong>read</strong> config options. Therefore all we care about is to
guarantee that:</p>
<ul class="simple">
<li>we get a valid config file at all times when reading,</li>
<li>we always leave a valid config file when writing (via the rename dance)</li>
</ul>
<p>From there, conceptually, all operations can clearly define whether or not
they need to modify a config file and do so only when they succeed. All
modifications occurring during such an operation are delayed until the very
end of the operation.</p>
<p>Now, we want to minimize the overlapping times where one bzr operation has
changed a value and another concurrent operation is unaware of this
modification.</p>
<p>These overlapping periods are <em>as of today</em> rare.</p>
<p>The only known case, <a class="reference external" href="http://pad.lv/525571">http://pad.lv/525571</a> has been fixed in bzr-2.1.3. The
bug there was triggered when two processes tried to write the same config
file at the same time leaving an invalid file in the end.</p>
<p>Such a period can be recognized and detected though: when changing an option
value, if the preserved original value is different in the config file,
someone else modified it and the operation can be invalid because it relied
on the original value.</p>
<p>For the sake of the example, if an option value represent a global unique ID
via a simple counter (very bad idea), if two operations try to increment it,
both will use the same value that won’t be unique anymore. Checking the
value present in the file when trying to save the updated value with
identify such a collision.</p>
<p>An assumption is floating around: it should be enough to report when an
operation is modifying an already modified option and observe that no-one
reports such occurrences.</p>
<p>Note that this assumption is made in a context where <em>no</em> known scenarios
exist in the bzr code base not in any plugin (for a best effort value of
‘any’, feedback highly welcome, bug reports even ;)</p>
<p>With this in mind, we can change the definition of config options, stores
and stacks to ensure that:</p>
<ul class="simple">
<li>a config file is read only once when in read access,</li>
<li>a config file is read only once and written only once when in write
access, adding the check mentioned above will require <em>one</em> additional
read.</li>
</ul>
<p>A reader can then safely assume that reading a config file gives it a valid
(and coherent) definition of the configuration when the operation
starts. All the operation has to do is to declare which config files may be
modified by an operation (whether or not we can be liberal on this ‘may be’
is yet to be defined).</p>
</div>
</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="#">Simplifying Bazaar Configuration</a><ul>
<li><a class="reference internal" href="#goal">Goal</a></li>
<li><a class="reference internal" href="#current-issues">Current issues</a></li>
<li><a class="reference internal" href="#proposed-implementation">Proposed implementation</a><ul>
<li><a class="reference internal" href="#configuration-files-definition">Configuration files definition</a></li>
<li><a class="reference internal" href="#naming">Naming</a></li>
<li><a class="reference internal" href="#value">Value</a></li>
<li><a class="reference internal" href="#option-expansion">Option expansion</a></li>
<li><a class="reference internal" href="#configuration-file-syntax">Configuration file syntax</a></li>
<li><a class="reference internal" href="#section-matching">Section matching</a><ul>
<li><a class="reference internal" href="#locationmatcher">LocationMatcher</a></li>
<li><a class="reference internal" href="#pathmatcher">PathMatcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-option-object">The Option object</a></li>
<li><a class="reference internal" href="#the-section-object">The Section object</a></li>
<li><a class="reference internal" href="#the-store-object">The Store object</a></li>
<li><a class="reference internal" href="#the-stack-object">The Stack object</a><ul>
<li><a class="reference internal" href="#getting-an-option-value">Getting an option value</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#compatibility">Compatibility</a></li>
<li><a class="reference internal" href="#notes">Notes</a><ul>
<li><a class="reference internal" href="#developer-facing-concepts">Developer facing concepts</a><ul>
<li><a class="reference internal" href="#option">Option</a></li>
<li><a class="reference internal" href="#stack">Stack</a></li>
<li><a class="reference internal" href="#stackregistry">StackRegistry</a></li>
<li><a class="reference internal" href="#store">Store</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
<li><a class="reference internal" href="#store-examples">store examples:</a></li>
</ul>
</li>
<li><a class="reference internal" href="#why-and-when-locking-config-files-matter">Why and when locking config files matter</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="performance-roadmap.html"
title="previous chapter">1 Bazaar Performance Roadmap</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tortoise-strategy.html"
title="next chapter">Bazaar Windows Shell Extension Options</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/new-config-rationale.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="tortoise-strategy.html" title="Bazaar Windows Shell Extension Options"
>next</a></li>
<li class="right" >
<a href="performance-roadmap.html" title="1 Bazaar Performance Roadmap"
>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">Developer Document Catalog (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="plans.html" >Plans</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>
