Rev 6562: Clarify option references expansion for `bzr config`. in file:///home/vila/src/bzr/bugs/996401-doc-config/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/bugs/996401-doc-config/

------------------------------------------------------------
revno: 6562
revision-id: v.ladeuil+lp at free.fr-20120918163802-97blgrccxnumg496
parent: pqm at pqm.ubuntu.com-20120917111425-4i6r0ze0v9zm33bu
fixes bug: https://launchpad.net/bugs/996401
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: 996401-doc-config
timestamp: Tue 2012-09-18 18:38:02 +0200
message:
  Clarify option references expansion for `bzr config`.
-------------- next part --------------
=== modified file 'bzrlib/config.py'
--- a/bzrlib/config.py	2012-09-17 08:45:19 +0000
+++ b/bzrlib/config.py	2012-09-18 16:38:02 +0000
@@ -4085,17 +4085,21 @@
 class cmd_config(commands.Command):
     __doc__ = """Display, set or remove a configuration option.
 
-    Display the active value for a given option.
+    Display the active value for option NAME.
 
     If --all is specified, NAME is interpreted as a regular expression and all
-    matching options are displayed mentioning their scope. The active value
-    that bzr will take into account is the first one displayed for each option.
-
-    If no NAME is given, --all .* is implied.
-
-    Setting a value is achieved by using name=value without spaces. The value
+    matching options are displayed mentioning their scope and without resolving
+    option references in the value). The active value that bzr will take into
+    account is the first one displayed for each option.
+
+    If NAME is not given, --all .* is implied (all options are displayed for the
+    current scope).
+
+    Setting a value is achieved by using NAME=value without spaces. The value
     is set in the most relevant scope and can be checked by displaying the
     option again.
+
+    Removing a value is achieved by using --remove NAME.
     """
 
     takes_args = ['name?']

=== modified file 'doc/en/release-notes/bzr-2.6.txt'
--- a/doc/en/release-notes/bzr-2.6.txt	2012-09-14 17:22:35 +0000
+++ b/doc/en/release-notes/bzr-2.6.txt	2012-09-18 16:38:02 +0000
@@ -63,6 +63,9 @@
 
 .. Improved or updated documentation.
 
+* Clarify ``bzr config`` usages especially around other option references
+  expansion. (Vincent Ladeuil, #996401)
+
 API Changes
 ***********
 

=== modified file 'doc/en/user-guide/configuring_bazaar.txt'
--- a/doc/en/user-guide/configuring_bazaar.txt	2011-05-02 08:15:59 +0000
+++ b/doc/en/user-guide/configuring_bazaar.txt	2012-09-18 16:38:02 +0000
@@ -129,6 +129,13 @@
 Each configuration file is associated with a given scope whose name is
 displayed before each set of defined options.
 
+If you need to look at a specific option, you can use::
+
+  bzr config <option>
+
+This will display only the option value and is intended to be used in
+scripts.
+
 Modifying the active configuration
 ----------------------------------
 
@@ -136,6 +143,29 @@
 
   bzr config opt=value
 
+An option value can reference another option by enclosing it in curly
+braces::
+
+  bzr config opt={other_opt}/subdir
+
+If ``other_opt`` is set to ``'root``, ``bzr config opt`` will display::
+
+  root/subdir
+
+Note that when ``--all`` is used, the references are left as-is to better
+reflect the content of the config files and make it easier to organize them::
+
+  bzr config --all .*opt
+
+  bazaar:
+    [DEFAULT]
+    opt = {other_opt}/subdir
+    other_opt = root
+
+
+
+
+
 To remove an option use::
 
   bzr config --remove opt