Rev 5462: Add some user-guide documentation for bzr config. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/experimental/config/

------------------------------------------------------------
revno: 5462
revision-id: v.ladeuil+lp at free.fr-20101013135944-2mt5pmr43ve2rvad
parent: v.ladeuil+lp at free.fr-20101013080136-7o5qbbwgxhgncsj8
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: config-modify
timestamp: Wed 2010-10-13 15:59:44 +0200
message:
  Add some user-guide documentation for bzr config.
-------------- next part --------------
=== modified file 'NEWS'
--- a/NEWS	2010-10-13 08:01:36 +0000
+++ b/NEWS	2010-10-13 13:59:44 +0000
@@ -22,6 +22,11 @@
   new or mirrored branch without working trees.
   (Matthew Gordon, #506730)
 
+* ``bzr config`` is a new command that displays the configuration options for
+  a given directory. It accepts a glob to match against multiple options at
+  once. It can also be used to set or delete a configuration option in any
+  configuration file. (Vincent Ladeuil)
+
 * New shortcut url schemes ``ubuntu:`` and ``debianlp:`` access source
   branches on Launchpad.  E.g. ``bzr branch ubuntu:foo`` gives you the source
   branch for project ``foo`` in the current distroseries for Ubuntu while
@@ -97,11 +102,6 @@
   a file upon an out of memory error.
   (Karl Bielefeldt, #551391)
 
-* ``bzr config`` is a new command that displays the configuration options for
-  a given directory. It accepts a glob to match against multiple options at
-  once. It can also be used to set or delete a configuration option in any
-  configuration file. (Vincent Ladeuil)
-
 * ``bzr status`` now displays a summary of existing shelves after
   the other status information. This is done using a ``post_status``
   hook.

=== modified file 'doc/en/user-guide/configuring_bazaar.txt'
--- a/doc/en/user-guide/configuring_bazaar.txt	2010-10-08 10:50:51 +0000
+++ b/doc/en/user-guide/configuring_bazaar.txt	2010-10-13 13:59:44 +0000
@@ -70,6 +70,59 @@
 in the Bazaar User Reference.
 
 
+Looking at the active configuration
+-----------------------------------
+
+To look at all the currently defined options, you can use the following
+command::
+
+  bzr config
+
+``bzr`` implements some rules to decide where to get the value of a
+configuration option.
+
+The current policy is to examine the existing configurations files in a
+given order for matching definitions.
+
+  * ``locations.conf`` is searched first for a section whose name matches the
+    location considered (working tree, branch or remote branch),
+
+  * the current ``branch.conf`` is searched next,
+
+  * ``bazaar.conf`` is searched next,
+
+  * finally, some options can have default values generally defined in the
+    code itself and not displayed by ``bzr config`` (see `Configuration
+    Settings <../user-reference/index.html#configuration-settings>`_).
+
+This is better understood by using ```bzr config`` with no arguments, which
+will display some output of the form::
+
+  locations:
+    post_commit_to = commits at example.com
+    news_merge_files = NEWS
+  branch:
+    parent_location = bzr+ssh://bazaar.launchpad.net/+branch/bzr/
+    nickname = config-modify
+    push_location = bzr+ssh://bazaar.launchpad.net/~vila/bzr/config-modify/
+  bazaar:
+    debug_flags = hpss,
+
+Each configuration file is associated with a given scope whose name is
+displayed before each set of defined options.
+
+Modifying the active configuration
+----------------------------------
+
+To set an option to a given value use::
+
+  bzr config opt=value
+
+To remove an option use::
+
+  bzr config --remove opt
+
+
 Rule-based preferences
 ----------------------