/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Jelmer Vernooij
  • Date: 2017-05-21 12:41:27 UTC
  • mto: This revision was merged to the branch mainline in revision 6623.
  • Revision ID: jelmer@jelmer.uk-20170521124127-iv8etg0vwymyai6y
s/bzr/brz/ in apport config.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
1
 
Configuring Breezy
 
1
Configuring Bazaar
2
2
==================
3
3
 
4
4
.. contents::
5
5
   :depth: 2
6
6
 
7
 
As a Breezy developer there are a few things you need to know about
 
7
As a Bazaar developer there are a few things you need to know about
8
8
configuration:
9
9
 
10
10
* how to add a new option,
31
31
----------------
32
32
 
33
33
You add a new ``Option`` to the ``option_registry``, either inside
34
 
``breezy/config.py`` or during initialization of your plugin (use
 
34
``bzrlib/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 ``brz config``).
 
58
left to the user (with ``bzr 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
63
63
 
64
64
But before doing that, you must be sure that the stack you're using have a
65
65
writable section (this is true for ``GlobalStack`` which uses the
66
 
``DEFAULT`` section in ``breezy.conf`` and for ``BranchStack``which uses the
 
66
``DEFAULT`` section in ``bazaar.conf`` and for ``BranchStack``which uses the
67
67
no-name section in ``branch.conf``).
68
68
 
69
69
Old and new configuration code
112
112
associated levels of generality and query them in the appropriate order
113
113
returning the first definition found. For example, the
114
114
``append_revisions_only`` option may be declared for all branches of a user
115
 
in ``breezy.conf``, or for a hierarchy of branches in ``locations.conf`` or
 
115
in ``bazaar.conf``, or for a hierarchy of branches in ``locations.conf`` or
116
116
in a single branch in ``branch.conf``.
117
117
 
118
118
Defining a new stack means you need a new way to expose these levels to the
135
135
Adding a new store
136
136
------------------
137
137
 
138
 
The following stores are used by ``brz`` in ways that illustrate various
 
138
The following stores are used by ``bzr`` in ways that illustrate various
139
139
uses of sections.
140
140
 
141
 
breezy.conf
 
141
bazaar.conf
142
142
===========
143
143
 
144
 
``brz`` itself defines two sections here:
 
144
``bzr`` 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 ``brz alias`` command uses it
 
149
  available via ``GlobalStack``, instead, the ``bzr 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
154
154
though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there
155
155
for example.
156
156
 
 
157
pkgimport.conf
 
158
==============
 
159
 
 
160
The Ubuntu package importer defines a store and two stacks involving
 
161
``pkgimport.conf``. A no-name section contains the options common to all
 
162
packages and sections named after their corresponding package can also be
 
163
defined.
 
164
 
 
165
The ``ImporterStack`` uses ``locations.conf`` and the no-name section in
 
166
``pkgimport.conf`` for the importer options.
 
167
 
 
168
The ``PackageStack`` uses only ``pkgimport.conf`` and uses the section name
 
169
after the package followed by the no-name section.
 
170
 
157
171
location.conf
158
172
=============
159
173
 
160
 
``brz`` defines sections corresponding to URLs there and includes the
 
174
``bzr`` defines sections corresponding to URLs there and includes the
161
175
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
162
176
section is recognized in this file.
163
177
 
195
209
  summary and can be followed by a blank line and a more detailed
196
210
  explanation. This will be displayed to the user with::
197
211
 
198
 
    brz help <option name>
 
212
    bzr help <option name>
199
213
 
200
214
* invalid: the action to be taken when an invalid value is encountered in a
201
215
  store (during a Stack.get()).
247
261
to implement a locking mechanism. ``LockableIniFileStore`` implements such a
248
262
mechanism for ``IniFileStore`` based stores.
249
263
 
250
 
Classes are provided for the usual Breezy configuration files and could be
 
264
Classes are provided for the usual Bazaar configuration files and could be
251
265
used as examples to define new ones if needed. The associated tests provides a
252
266
basis for new classes which only need to register themselves in the right
253
267
places to inherit from the existing basic tests and add their own specific
259
273
 
260
274
* defining how the values are quoted/unquoted for storage purposes. Stacks
261
275
  use the unquoted values internally (default value handling and option
262
 
  expansion are simpler this way) and ``brz config`` quote them when they
 
276
  expansion are simpler this way) and ``bzr config`` quote them when they
263
277
  need to be displayed.
264
278
 
265
279
 
296
310
Specific section matchers can be implemented by overriding ``get_sections``
297
311
or just ``match``.
298
312
 
299
 
``breezy`` provides:
 
313
``bzrlib`` provides:
300
314
 
301
315
* ``NameMatcher(store, unique_id)``: To select a single section matching
302
316
  ``unique_id``.
312
326
 
313
327
An option can take different values depending on the context it is
314
328
used. This can involve configuration files, options from the command line,
315
 
default values in breezy and then some.
 
329
default values in bzrlib and then some.
316
330
 
317
331
Such a context is implemented by creating a list of ``Section`` stacked upon
318
332
each other. A ``Stack`` can then be asked for an option value and returns the
347
361
allows for simpler and faster tests. A common pattern is to accept a
348
362
``config`` parameter related to a given feature and test it with predefined
349
363
configurations without involving the whole
350
 
stack. ``breezy.tests.test_commit``, ``breezy.tests.test_gpg`` and
351
 
``breezy.tests.test_smtp_connection`` are good examples.
 
364
stack. ``bzrlib.tests.test_commit``, ``bzrlib.tests.test_gpg`` and
 
365
``bzrlib.tests.test_smtp_connection`` are good examples.
352
366