← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/configuration.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2008-03-16 14:01:20 UTC
  • mfrom: (3280.2.5 integration)
  • Revision ID: pqm@pqm.ubuntu.com-20080316140120-i3yq8yr1l66m11h7
Start 1.4 development

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help_topics/en/configuration.txt
1
1
Configuration Settings
2
2
=======================
3
3
 
 
4
.. TODO: Should have some explanation of why you'd want things in
 
5
.. branch.conf.
 
6
 
 
7
 
4
8
Environment settings
5
9
---------------------
6
10
 
59
63
 
60
64
Path to the editor Bazaar should use for commit messages, etc.
61
65
 
62
 
BZR_LOG
63
 
~~~~~~~
64
 
 
65
 
Location of the Bazaar log file. You can check the current location by
66
 
running ``bzr version``.
67
 
 
68
 
The log file contains debug information that is useful for diagnosing or
69
 
reporting problems with Bazaar.
70
 
 
71
 
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
72
 
will disable logging.
73
 
 
74
 
 
75
66
BZR_PLUGIN_PATH
76
67
~~~~~~~~~~~~~~~
77
68
 
78
69
The path to the plugins directory that Bazaar should use.
79
 
If not set, Bazaar will search for plugins in:
80
 
 
81
 
* the user specific plugin directory (containing the ``user`` plugins),
82
 
 
83
 
* the bzrlib directory (containing the ``core`` plugins),
84
 
 
85
 
* the site specific plugin directory if applicable (containing
86
 
  the ``site`` plugins).
87
 
 
88
 
If ``BZR_PLUGIN_PATH`` is set in any fashion, it will change the
89
 
the way the plugin are searched. 
90
 
 
91
 
As for the ``PATH`` variables, if multiple directories are
92
 
specified in ``BZR_PLUGIN_PATH`` they should be separated by the
93
 
platform specific appropriate character (':' on Unix,
94
 
';' on windows)
95
 
 
96
 
By default if ``BZR_PLUGIN_PATH`` is set, it replaces searching
97
 
in ``user``.  However it will continue to search in ``core`` and
98
 
``site`` unless they are explicitly removed.
99
 
 
100
 
If you need to change the order or remove one of these
101
 
directories, you should use special values:
102
 
 
103
 
* ``-user``, ``-core``, ``-site`` will remove the corresponding
104
 
  path from the default values,
105
 
 
106
 
* ``+user``, ``+core``, ``+site`` will add the corresponding path
107
 
  before the remaining default values (and also remove it from
108
 
  the default values).
109
 
 
110
 
Note that the special values 'user', 'core' and 'site' should be
111
 
used literally, they will be substituted by the corresponding,
112
 
platform specific, values.
113
 
 
114
 
The examples below use ':' as the separator, windows users
115
 
should use ';'.
116
 
 
117
 
Overriding the default user plugin directory::
118
 
 
119
 
  BZR_PLUGIN_PATH='/path/to/my/other/plugins'
120
 
 
121
 
Disabling the site directory while retaining the user directory::
122
 
 
123
 
  BZR_PLUGIN_PATH='-site:+user'
124
 
 
125
 
Disabling all plugins (better achieved with --no-plugins)::
126
 
 
127
 
  BZR_PLUGIN_PATH='-user:-core:-site'
128
 
 
129
 
Overriding the default site plugin directory::
130
 
 
131
 
  BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user
132
 
 
133
 
BZR_DISABLE_PLUGINS
134
 
~~~~~~~~~~~~~~~~~~~
135
 
 
136
 
Under special circumstances (mostly when trying to diagnose a
137
 
bug), it's better to disable a plugin (or several) rather than
138
 
uninstalling them completely. Such plugins can be specified in
139
 
the ``BZR_DISABLE_PLUGINS`` environment variable.
140
 
 
141
 
In that case, ``bzr`` will stop loading the specified plugins and
142
 
will raise an import error if they are explicitly imported (by
143
 
another plugin that depends on them for example).
144
 
 
145
 
Disabling ``myplugin`` and ``yourplugin`` is achieved by::
146
 
 
147
 
  BZR_DISABLE_PLUGINS='myplugin:yourplugin'
148
 
 
149
 
BZR_PLUGINS_AT
150
 
~~~~~~~~~~~~~~
151
 
 
152
 
When adding a new feature or working on a bug in a plugin,
153
 
developers often need to use a specific version of a given
154
 
plugin. Since python requires that the directory containing the
155
 
code is named like the plugin itself this make it impossible to
156
 
use arbitrary directory names (using a two-level directory scheme
157
 
is inconvenient). ``BZR_PLUGINS_AT`` allows such directories even
158
 
if they don't appear in ``BZR_PLUGIN_PATH`` .
159
 
 
160
 
Plugins specified in this environment variable takes precedence
161
 
over the ones in ``BZR_PLUGIN_PATH``.
162
 
 
163
 
The variable specified a list of ``plugin_name@plugin path``,
164
 
``plugin_name`` being the name of the plugin as it appears in
165
 
python module paths, ``plugin_path`` being the path to the
166
 
directory containing the plugin code itself
167
 
(i.e. ``plugins/myplugin`` not ``plugins``).  Use ':' as the list
168
 
separator, use ';' on windows.
169
 
 
170
 
Example:
171
 
~~~~~~~~
172
 
 
173
 
Using a specific version of ``myplugin``:
174
 
``BZR_PLUGINS_AT='myplugin@/home/me/bugfixes/123456-myplugin``
175
70
 
176
71
BZRPATH
177
72
~~~~~~~
179
74
The path where Bazaar should look for shell plugin external commands.
180
75
 
181
76
 
182
 
http_proxy, https_proxy
183
 
~~~~~~~~~~~~~~~~~~~~~~~
184
 
 
185
 
Specifies the network proxy for outgoing connections, for example::
186
 
 
187
 
  http_proxy=http://proxy.example.com:3128/ 
188
 
  https_proxy=http://proxy.example.com:3128/
189
 
 
190
 
 
191
77
Configuration files
192
78
-------------------
193
79
 
194
80
Location
195
81
~~~~~~~~
196
82
 
197
 
Configuration files are located in ``$HOME/.bazaar`` on Unix and
 
83
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
198
84
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
199
85
Windows. (You can check the location for your system by using
200
86
``bzr version``.)
236
122
 
237
123
    [DEFAULT]
238
124
 
239
 
The only valid section headers for bazaar.conf currently are [DEFAULT] and
240
 
[ALIASES].  Section headers are case sensitive. The default section provides for
241
 
setting variables which can be overridden with the branch config file.
 
125
The only valid section header for bazaar.conf is [DEFAULT], which is
 
126
case sensitive. The default section provides for setting variables
 
127
which can be overridden with the branch config file.
242
128
 
243
129
For ``locations.conf``, the variables from the section with the
244
130
longest matching section header are used to the exclusion of other
292
178
The main configuration file, bazaar.conf
293
179
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294
180
 
295
 
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
296
 
The default section contains the default
 
181
``bazaar.conf`` only allows one
 
182
section called ``[DEFAULT]``. This default section contains the default
297
183
configuration options for all branches. The default section can be
298
184
overriden by providing a branch-specific section in ``locations.conf``.
299
185
 
336
222
variable policies which don't apply.
337
223
 
338
224
For more information on the possible uses of the authentication configuration
339
 
file see :doc:`authentication-help`.
 
225
file see `Authentication Settings`_.
340
226
 
341
227
 
342
228
Common variable options
343
229
-----------------------
344
230
 
345
 
debug_flags
346
 
~~~~~~~~~~~
347
 
 
348
 
A comma-separated list of debugging options to turn on.  The same values
349
 
can be used as with the -D command-line option (see `help global-options`).
350
 
For example::
351
 
 
352
 
    debug_flags = hpss
353
 
 
354
231
email
355
232
~~~~~
356
233
 
367
244
``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
368
245
variables.
369
246
 
370
 
log_format
371
 
~~~~~~~~~~
372
 
 
373
 
The default log format to use. Standard log formats are ``long``, ``short``
374
 
and ``line``. Additional formats may be provided by plugins. The default
375
 
value is ``long``.
376
 
 
377
247
check_signatures
378
248
~~~~~~~~~~~~~~~~
379
249
 
463
333
 
464
334
Supported values for specific clients:
465
335
 
466
 
:claws: Use Claws.  This skips a dialog for attaching files.
467
336
:evolution: Use Evolution.
468
337
:kmail: Use KMail.
469
338
:mutt: Use Mutt.
492
361
A publically-accessible version of this branch (implying that this version is
493
362
not publically-accessible).  Used (and set) by ``bzr send``.
494
363
 
495
 
suppress_warnings
496
 
~~~~~~~~~~~~~~~~~
497
 
 
498
 
A list of strings, each string represent a warning that can be emitted by
499
 
bzr. Mentioning a warning in this list tells bzr to not emit it.
500
 
 
501
 
Valid values:
502
 
 
503
 
* ``format_deprecation``:
504
 
    whether the format deprecation warning is shown on repositories that are
505
 
    using deprecated formats.
506
 
 
507
 
 
508
 
Unicode options
509
 
---------------
510
 
 
511
 
output_encoding
512
 
~~~~~~~~~~~~~~~
513
 
 
514
 
A Python unicode encoding name for text output from bzr, such as log
515
 
information.  Values include: utf8, cp850, ascii, iso-8859-1.  The default
516
 
is the terminal encoding prefered by the operating system.
517
 
 
518
364
 
519
365
Branch type specific options
520
366
----------------------------
528
374
~~~~~~~~~~~~~~~~~~~~~
529
375
 
530
376
If set to "True" then revisions can only be appended to the log, not
531
 
removed.  A branch with this setting enabled can only pull from another
532
 
branch if the other branch's log is a longer version of its own.  This is
533
 
normally set by ``bzr init --append-revisions-only``. If you set it
534
 
manually, use either 'True' or 'False' (case-sensitive) to maintain
535
 
compatibility with previous bzr versions (older than 2.2).
 
377
removed.  A branch with this setting enabled can only pull from
 
378
another branch if the other branch's log is a longer version of its
 
379
own.  This is normally set by ``bzr init --append-revisions-only``.
536
380
 
537
381
parent_location
538
382
~~~~~~~~~~~~~~~
547
391
If present, the location of the default branch for push.  This option
548
392
is normally set by ``push --remember``.
549
393
 
550
 
push_strict
551
 
~~~~~~~~~~~
552
 
 
553
 
If present, defines the ``--strict`` option default value for checking
554
 
uncommitted changes before pushing.
555
 
 
556
 
dpush_strict
557
 
~~~~~~~~~~~~
558
 
 
559
 
If present, defines the ``--strict`` option default value for checking
560
 
uncommitted changes before pushing into a different VCS without any
561
 
custom bzr metadata.
562
 
 
563
394
bound_location
564
395
~~~~~~~~~~~~~~
565
396
 
571
402
 
572
403
If set to "True", the branch should act as a checkout, and push each commit to
573
404
the bound_location.  This option is normally set by ``bind``/``unbind``.
574
 
 
575
 
send_strict
576
 
~~~~~~~~~~~
577
 
 
578
 
If present, defines the ``--strict`` option default value for checking
579
 
uncommitted changes before sending a merge directive.
580