/breezy/unstable

To get this branch, use:
bzr branch https://code.breezy-vcs.org/breezy/unstable

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Jelmer Vernooij
  • Date: 2017-05-24 01:39:33 UTC
  • mfrom: (3815.3776.6)
  • Revision ID: jelmer@jelmer.uk-20170524013933-ir4y4tqtrsiz2ka2
New upstream snapshot.

Show diffs side-by-side

added added

removed removed

Lines of Context:
31
31
----------------
32
32
 
33
33
You add a new ``Option`` to the ``option_registry``, either inside
34
 
``bzrlib/config.py`` or during initialization of your plugin (use
 
34
``breezy/config.py`` or during initialization of your plugin (use
35
35
``register_lazy`` in this case). New plugins should have systematic
36
36
hierarchical names so that related values are grouped together::
37
37
 
55
55
 
56
56
Just reading an option is what is needed most of the time, modifying option
57
57
values or removing options is usually something that is not automated but
58
 
left to the user (with ``bzr config``).
 
58
left to the user (with ``brz config``).
59
59
 
60
60
Nevertheless, if you need to save a modified option value, use
61
61
``.set(option_name, value)`` and ``.remove(option_name)`` to delete the
135
135
Adding a new store
136
136
------------------
137
137
 
138
 
The following stores are used by ``bzr`` in ways that illustrate various
 
138
The following stores are used by ``brz`` in ways that illustrate various
139
139
uses of sections.
140
140
 
141
141
bazaar.conf
142
142
===========
143
143
 
144
 
``bzr`` itself defines two sections here:
 
144
``brz`` itself defines two sections here:
145
145
 
146
146
* ``DEFAULT`` where global options are defined,
147
147
 
148
148
* ``ALIASES`` where command aliases are defined. This section is *not*
149
 
  available via ``GlobalStack``, instead, the ``bzr alias`` command uses it
 
149
  available via ``GlobalStack``, instead, the ``brz alias`` command uses it
150
150
  for its own purposes.
151
151
 
152
152
Plugins can define either additional options in the ``DEFAULT`` section or
171
171
location.conf
172
172
=============
173
173
 
174
 
``bzr`` defines sections corresponding to URLs there and includes the
 
174
``brz`` defines sections corresponding to URLs there and includes the
175
175
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
176
176
section is recognized in this file.
177
177
 
209
209
  summary and can be followed by a blank line and a more detailed
210
210
  explanation. This will be displayed to the user with::
211
211
 
212
 
    bzr help <option name>
 
212
    brz help <option name>
213
213
 
214
214
* invalid: the action to be taken when an invalid value is encountered in a
215
215
  store (during a Stack.get()).
273
273
 
274
274
* defining how the values are quoted/unquoted for storage purposes. Stacks
275
275
  use the unquoted values internally (default value handling and option
276
 
  expansion are simpler this way) and ``bzr config`` quote them when they
 
276
  expansion are simpler this way) and ``brz config`` quote them when they
277
277
  need to be displayed.
278
278
 
279
279
 
310
310
Specific section matchers can be implemented by overriding ``get_sections``
311
311
or just ``match``.
312
312
 
313
 
``bzrlib`` provides:
 
313
``breezy`` provides:
314
314
 
315
315
* ``NameMatcher(store, unique_id)``: To select a single section matching
316
316
  ``unique_id``.
326
326
 
327
327
An option can take different values depending on the context it is
328
328
used. This can involve configuration files, options from the command line,
329
 
default values in bzrlib and then some.
 
329
default values in breezy and then some.
330
330
 
331
331
Such a context is implemented by creating a list of ``Section`` stacked upon
332
332
each other. A ``Stack`` can then be asked for an option value and returns the
361
361
allows for simpler and faster tests. A common pattern is to accept a
362
362
``config`` parameter related to a given feature and test it with predefined
363
363
configurations without involving the whole
364
 
stack. ``bzrlib.tests.test_commit``, ``bzrlib.tests.test_gpg`` and
365
 
``bzrlib.tests.test_smtp_connection`` are good examples.
 
364
stack. ``breezy.tests.test_commit``, ``breezy.tests.test_gpg`` and
 
365
``breezy.tests.test_smtp_connection`` are good examples.
366
366