Rev 5518: One more pass taking into account ``bzr config``. in file:///home/vila/src/bzr/experimental/config/
Vincent Ladeuil
v.ladeuil+lp at free.fr
Fri Nov 12 14:43:20 GMT 2010
At file:///home/vila/src/bzr/experimental/config/
------------------------------------------------------------
revno: 5518
revision-id: v.ladeuil+lp at free.fr-20101112144320-mdyou57x6gk2sja9
parent: v.ladeuil+lp at free.fr-20101112093736-o8tijztrb15tcqfl
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Fri 2010-11-12 15:43:20 +0100
message:
One more pass taking into account ``bzr config``.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt 2010-11-01 13:20:01 +0000
+++ b/doc/developers/configuration.txt 2010-11-12 14:43:20 +0000
@@ -5,11 +5,12 @@
Goal
====
-Not all needs can be addressed by the default values, no matter how well
-they are chosen.
+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 ;).
-Many parts of ``bzrlib`` depends on options though and the user should be
-able to customize the behavior to suit his needs.
+Many parts of ``bzrlib`` 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.
These options can be set from the command-line, in an environment variable
or recorded in a configuration file.
@@ -21,10 +22,11 @@
user to look at or modify them.
* The current API requires a configuration object to create, modify or
- delete a configuration option in a given configuration file. While this
- matches the user expectations developers would be better served by
- manipulating configuration option objects directly, providing a branch,
- working tree or repository to define the context for this option.
+ delete a configuration option in a given configuration file. ``bzr
+ config`` 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.
* ``locations.conf`` defines the options that needs to override any setting
in ``branch.conf`` for both local and remotes branches. Many users want a
@@ -42,23 +44,16 @@
* should the inherited value append the relative path between the
section one and the location it applies to.
- * the default value (including calling any python code that may is
+ * the default value (including calling any python code that may be
required to calculate this value),
- * are the rules above different for various config files
-
-* There is no way to get access to the configuration option active value
- from the command line. The "active" value is the one that ``bzr`` will
- take into account when excuting a command. Access to this value should
- be possible for all contexts:
-
- * for a given local or remote branch,
-
- * for a given section in a given configuration file.
-
-* There is no way to modify or delete a configuration option. Again, it
- should be possible to do so for any local or remote branch and any
- section of any configuration file.
+ * priority between sections and various config files
+
+* Access to the 'active' configuration option value from the command line
+ doesn't give access to specific section.
+
+* Rules for configuration options are not clearly defined for remote
+ branches (they may differ between dumb and smart servers).
* The features offered by the Bazaar configuration files should be easily
accessible to plugin authors either by supporting plugin configuration
@@ -66,7 +61,7 @@
own configuration files.
* While the actual configuration files support sections, they are used in
- mutually exclusive ways to make it impossible to offer the same set of
+ mutually exclusive ways that make it impossible to offer the same set of
features to all configuration files:
* ``bazaar.conf`` use arbitrary names for sections. ``DEFAULT`` is used
@@ -83,28 +78,32 @@
* 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 a often
+ 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*in* a working tree could also help
+ trees. Being able to specify options *in* a working tree could also help
support conflict resolution options for a given file, directory or
subtree.
* Since sections allow different definitions for the same option, a total
order should be defined between sections to select the right definition
for a given path. Allowing globs for section names is harmful in this
- respect since the order is currently defined as being the
- lexicographical one. 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.
+ respect since the order is currently defined as being the lexicographical
+ one. 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 lenght in a grey area but in practive using ``bzr config``
+ should give enough feedback to address them).
-* Internally, configuration files (and their fallbacks, ``bazaar.conf``
- and ``locatons.conf`` for ``branch.conf``) are read each time *one*
- option is queried. Likewise, setting or deleting a configuration option
- implies writing the configuration file *immediately* after re-reading
- the file to avoid racing updates.
+* Internally, configuration files (and their fallbacks, ``bazaar.conf`` and
+ ``locatons.conf`` for ``branch.conf``) are read every time *one* option is
+ queried. Likewise, setting or deleting a configuration option implies
+ writing the configuration file *immediately* after re-reading the file to
+ avoid racing updates.
* The current implementation use a mix of transport-based and direct file
systems operations.
@@ -118,8 +117,32 @@
* Inherited list values can't be modified, a more specific configuration can
only redefine the whole list.
+* 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 practivcal either if we keep using a no-name section
+ for default values. As a last resort, the value of such a configuration
+ option can be bencoded but that won't be user-friendly. This is not a big
+ concern so far as very few needs required dicts as option values.
+
+Proposed implementation
+=======================
+
+
+Configuration files definition
+------------------------------
+
+While of course configurations files can be versioned they are not intended
+to be accessed in sync with the files they refer too (one can imagine
+handling versioned properties this way but this is *not* what the bazaar
+configuration files are targeted at). ``bzr`` will always refer to
+configuration files as they exist on disk when an option is queried or set.
+
+The configuration files are generally local to the file system but some of
+them can be accessed remotely (branch.conf, repo.conf).
+
+
Naming
-======
+------
The option name space is organized as follow:
@@ -132,7 +155,7 @@
do so in the future).
Value
-=====
+-----
All option values are text. They are provided as Unicode strings to API
users with some refinements:
@@ -163,27 +186,31 @@
Since options values are text-only, and to avoid clashing with other
interpolation syntaxes, references are enclosed with curly brackets::
- push_location=lp:~{launchpad_username}/bzr/{nick}
+ push_location = lp:~{launchpad_username}/bzr/{nick}
In the example above, ``launchpad_username`` is an already defined
configuration option while ``nick`` is the branch nickname and is set when a
configuration applies to a given branch.
-The interpolation implementation accept an additional dict so that
+The interpolation implementation should accept an additional dict so that
``bzrlib`` or plugins can define references that can be interpolated without
being existing configuration options::
diff_command={cmd} {cmd_opts} {file_a} {file_b}
-There are two common errors that should handled when handling interpolation:
+There are two common errors that should be handled when handling interpolation:
* loops: when a configuration value refers to itself, directly or indirectly,
* undefined references: when a configuration value refers to an unknown option.
-The former can be addressed by falling back to the less specific
-configurations when a value is searched for. This allows list values to
-refer to the definition in the less specific configurations allowing::
+One possible implementation is to report errors when such references are
+encountered.
+
+Another implementation could be envisioned though: when a loop is
+encountered, we can fall back to the less specific configurations. This
+allows list values to refer to the definition in the less specific
+configurations allowing::
bazaar.conf:
debug_flags = hpss
@@ -191,26 +218,15 @@
branch.conf for mybranch:
debug_flags = {debug_flags}, hpssdetail
- $ bzr -d mybranch config -1 debug_flags
+ $ bzr -d mybranch config debug_flags
hpss, hpssdetail
Undefined references would still be detected if they are not defined in any
-configuration.
-
-Configuration files
-===================
-
-While of course configurations files can be versioned they are not intended
-to be accessed in sync with the files they refer too (one can imagine
-handling versioned properties this way but this is *not* what the bazaar
-configuration files are targeted at. ``bzr`` will always refer to
-configuration files as they exist on disk when an option is queried or set.
-
-The configuration files are generally local to the file system but some of
-them can be accessed remotely (branch.conf, repo.conf).
+configuration or just stay unresolved which should be enough to trigger
+errors displaying the value. Diagnosing typos should be doable in this case.
Configuration file syntax
-=========================
+-------------------------
The configuration file is mostly an ``ini-file``. It contains ``name =
value`` lines grouped in sections. Comments are allowed by prefixing them
@@ -219,14 +235,14 @@
A section is named by the path it should apply to (more examples below).
Options defined outside of any section act as defaults when no section
-apply. This means that in the most common cases, the user doesn't need to
+applies. This means that in the most common cases, the user doesn't need to
define any section.
When sections are used, they provide a finer grain of configuration by
-defining set of options that apply to some working trees, branches,
+defining option sets that apply to some working trees, branches,
repositories or part of them.
-The subset is defined by the common leading path.
+The subset is defined by the common leading path or a glob.
* a full url: used to described options for remote branches and
repositories.
@@ -234,17 +250,27 @@
* local absolute path: used for working trees, branches or repositories
on the local disks.
-* 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.
+* 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 ``.bzr`` and refers to threads in a loom for
+ example, the relative path would be the thread name, it doesn't have to be
+ an *exact* relative path, as long as its interpretation is unambiguous and
+ clear for the user).
Whatever path is used, the options apply if the branch path starts with
-the path defining the section.
+the path defining the section (or if the glob matches).
The ConfigOption object
-=======================
+-----------------------
+
+In addition to the configuration files, one internal configuration dict can
+contain definitions for some configuration options. This will allow a finer
+grained definition of the default values and the online help.
+
+The ConfigOption object will define:
* name
@@ -252,18 +278,14 @@
* docstring used for the help
-* a list of config files where the option can be defined. Depending on the
- files involved, a working tree, branch or repository object should be
- provided to the API to access the corresponding configuration file. Note
- that providing a working tree object also implicitely provides the
- associated branch and repository object so only one of them is required
- (or none for configuration files specific to the user like bazaar.conf and
- locations.conf).
+* a list of config files where the option can be defined.
The ConfigFile object
-=====================
-
-* local or remote
+---------------------
+
+This is an implementation-level object that should rarely be used directly.
+
+* it can be local or remote
* locking
@@ -273,19 +295,39 @@
Working trees, branches and repositories should define a config attribute
following the same life cycle as their lock: the associated config file is
- read one and written once if needed. This should minimize the file system
+ 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
- constraint one shouldn't introduce any. Yet, in order to detect such
+ constrained one shouldn't introduce any. Yet, in order to detect such
racing scenarios, we can check that the current content of the
configuration file is the expected one before writing the new content and
emit warnings if differences occurred. The checks should be performed for
- the modified values only.
-
-* fallback ConfigFile
+ the modified values only. As of today, the size of the configuration files
+ are small enough to be kept in memory.
+
+The Config object
+-----------------
+
+This the object that provides access to the needed features:
+
+* getting an option value,
+
+* setting an option value,
+
+* deleting an option value,
+
+* handling a list of configuration files that should be tried in the given
+ order to find an option.
+
+Depending on the files involved, a working tree, branch or repository object
+should be provided to access the corresponding configuration files. Note
+that providing a working tree object also implicitely provides the
+associated branch and repository object so only one of them is required (or
+none for configuration files specific to the user like bazaar.conf and
+locations.conf).
Getting an option value
-=======================
+~~~~~~~~~~~~~~~~~~~~~~~
Depending on the option, there are various places where it can be defined
and several ways to override these settings when needed.
@@ -326,11 +368,14 @@
The options related to the branch.
- Sections can
+ Sections can be defined for co-located branches or loom threads.
* repo.conf (Not Implemented Yet)
- The options related to the repository
+ The options related to the repository.
+
+ Using an option to describe whether or not a repository is shared could
+ help address bug #342119 but this will probably requires a format bump).
* project.conf (Not Implemented Yet)
@@ -344,10 +389,15 @@
The options the user has selected for the host he is using.
+ Sections can be defined for both remote and local branches to define
+ default values (i.e. the most common use of ``locations.conf`` today).
+
* default (Not Implemented Yet)
The options defined in the ``bzr`` source code.
+ This will be implemented via the ConfigOption objects.
+
Plugins can define additional configuration files as they see fit and
insert them in this list, see their documentation for details.
@@ -362,8 +412,6 @@
future. Plugin authors are encouraged to migrate to the new name space
scheme by prefixing their options with their plugin name.
-* Globs in section names are discouraged and should be deprecated.
-
* Option policies should be deprecated:
* The ``norecurse`` policy is useless, all options are recursive by
More information about the bazaar-commits
mailing list