~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Jonathan Riddell
  • Date: 2011-05-16 11:27:37 UTC
  • mto: This revision was merged to the branch mainline in revision 5869.
  • Revision ID: jriddell@canonical.com-20110516112737-gep642p24rtzp3jt
user guide licence

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Configuration Settings
 
2
=======================
 
3
 
 
4
Environment settings
 
5
---------------------
 
6
 
 
7
While most configuration is handled by configuration files, some options
 
8
which may be semi-permanent can also be controlled through the environment.
 
9
 
 
10
BZR_EMAIL
 
11
~~~~~~~~~
 
12
 
 
13
Override the email id used by Bazaar.  Typical format::
 
14
 
 
15
  "John Doe <jdoe@example.com>"
 
16
 
 
17
See also the ``email`` configuration value.
 
18
 
 
19
BZR_PROGRESS_BAR
 
20
~~~~~~~~~~~~~~~~
 
21
 
 
22
Override the progress display.  Possible values are "none", "dots", "tty"
 
23
 
 
24
BZR_SIGQUIT_PDB
 
25
~~~~~~~~~~~~~~~
 
26
 
 
27
Control whether SIGQUIT behaves normally or invokes a breakin debugger.
 
28
 
 
29
* 0 = Standard SIGQUIT behavior (normally, exit with a core dump)
 
30
* 1 = Invoke breakin debugger (default)
 
31
 
 
32
BZR_HOME
 
33
~~~~~~~~
 
34
 
 
35
Override the home directory used by Bazaar.
 
36
 
 
37
BZR_SSH
 
38
~~~~~~~
 
39
 
 
40
Select a different SSH implementation.
 
41
 
 
42
BZR_PDB
 
43
~~~~~~~
 
44
 
 
45
Control whether to launch a debugger on error.
 
46
 
 
47
* 0 = Standard behavior
 
48
* 1 = Launch debugger
 
49
 
 
50
BZR_REMOTE_PATH
 
51
~~~~~~~~~~~~~~~
 
52
 
 
53
Path to the Bazaar executable to use when using the bzr+ssh protocol.
 
54
 
 
55
See also the ``bzr_remote_path`` configuration value.
 
56
 
 
57
BZR_EDITOR
 
58
~~~~~~~~~~
 
59
 
 
60
Path to the editor Bazaar should use for commit messages, etc.
 
61
 
 
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
BZR_PLUGIN_PATH
 
76
~~~~~~~~~~~~~~~
 
77
 
 
78
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
 
 
176
BZRPATH
 
177
~~~~~~~
 
178
 
 
179
The path where Bazaar should look for shell plugin external commands.
 
180
 
 
181
 
 
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
Configuration files
 
192
-------------------
 
193
 
 
194
Location
 
195
~~~~~~~~
 
196
 
 
197
Configuration files are located in ``$HOME/.bazaar`` on Unix and
 
198
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
 
199
Windows. (You can check the location for your system by using
 
200
``bzr version``.)
 
201
 
 
202
There are three primary configuration files in this location:
 
203
 
 
204
* ``bazaar.conf`` describes default configuration options,
 
205
 
 
206
* ``locations.conf`` describes configuration information for
 
207
  specific branch locations,
 
208
 
 
209
* ``authentication.conf`` describes credential information for
 
210
  remote servers.
 
211
 
 
212
Each branch can also contain a configuration file that sets values specific
 
213
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
 
214
branch. This file is visible to all users of a branch, if you wish to override
 
215
one of the values for a branch with a setting that is specific to you then you
 
216
can do so in ``locations.conf``.
 
217
 
 
218
General format
 
219
~~~~~~~~~~~~~~
 
220
 
 
221
An ini file has three types of contructs: section headers, section
 
222
variables and comments.
 
223
 
 
224
Comments
 
225
^^^^^^^^
 
226
 
 
227
A comment is any line that starts with a "#" (sometimes called a "hash
 
228
mark", "pound sign" or "number sign"). Comment lines are ignored by
 
229
Bazaar when parsing ini files.
 
230
 
 
231
Section headers
 
232
^^^^^^^^^^^^^^^
 
233
 
 
234
A section header is a word enclosed in brackets that starts at the begining
 
235
of a line.  A typical section header looks like this::
 
236
 
 
237
    [DEFAULT]
 
238
 
 
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.
 
242
 
 
243
For ``locations.conf``, the variables from the section with the
 
244
longest matching section header are used to the exclusion of other
 
245
potentially valid section headers. A section header uses the path for
 
246
the branch as the section header. Some examples include::
 
247
 
 
248
    [http://mybranches.isp.com/~jdoe/branchdir]
 
249
    [/home/jdoe/branches/]
 
250
 
 
251
 
 
252
Section variables
 
253
^^^^^^^^^^^^^^^^^
 
254
 
 
255
A section variable resides within a section. A section variable contains a
 
256
variable name, an equals sign and a value.  For example::
 
257
 
 
258
    email            = John Doe <jdoe@isp.com>
 
259
    check_signatures = require
 
260
 
 
261
A variable can reference other variables **in the same configuration file** by
 
262
enclosing them in curly brackets::
 
263
 
 
264
    my_branch_name = feature_x
 
265
    my_server      = bzr+ssh://example.com
 
266
    push_location   = {my_server}/project/{my_branch_name}
 
267
 
 
268
 
 
269
Variable policies
 
270
^^^^^^^^^^^^^^^^^
 
271
 
 
272
Variables defined in a section affect the named directory or URL plus
 
273
any locations they contain.  Policies can be used to change how a
 
274
variable value is interpreted for contained locations.  Currently
 
275
there are three policies available:
 
276
 
 
277
 none:
 
278
   the value is interpreted the same for contained locations.  This is
 
279
   the default behaviour.
 
280
 norecurse:
 
281
   the value is only used for the exact location specified by the
 
282
   section name.
 
283
 appendpath:
 
284
   for contained locations, any additional path components are
 
285
   appended to the value.
 
286
 
 
287
Policies are specified by keys with names of the form "$var:policy".
 
288
For example, to define the push location for a tree of branches, the
 
289
following could be used::
 
290
 
 
291
  [/top/location]
 
292
  push_location = sftp://example.com/location
 
293
  push_location:policy = appendpath
 
294
 
 
295
With this configuration, the push location for ``/top/location/branch1``
 
296
would be ``sftp://example.com/location/branch1``.
 
297
 
 
298
 
 
299
The main configuration file, bazaar.conf
 
300
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
301
 
 
302
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
 
303
The default section contains the default
 
304
configuration options for all branches. The default section can be
 
305
overriden by providing a branch-specific section in ``locations.conf``.
 
306
 
 
307
A typical ``bazaar.conf`` section often looks like the following::
 
308
 
 
309
    [DEFAULT]
 
310
    email             = John Doe <jdoe@isp.com>
 
311
    editor            = /usr/bin/vim
 
312
    check_signatures  = check-available
 
313
    create_signatures = when-required
 
314
 
 
315
 
 
316
The branch location configuration file, locations.conf
 
317
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
318
 
 
319
``locations.conf`` allows one to specify overriding settings for
 
320
a specific branch. The format is almost identical to the default section in
 
321
bazaar.conf with one significant change: The section header, instead of saying
 
322
default, will be the path to a branch that you wish to override a value
 
323
for. The '?' and '*' wildcards are supported::
 
324
 
 
325
    [/home/jdoe/branches/nethack]
 
326
    email = Nethack Admin <nethack@nethack.com>
 
327
 
 
328
    [http://hypothetical.site.com/branches/devel-branch]
 
329
    create_signatures = always
 
330
    check_signatures  = always
 
331
 
 
332
    [http://example.com/bzr/*]
 
333
    check_signatures  = require
 
334
 
 
335
The authentication configuration file, authentication.conf
 
336
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
337
 
 
338
``authentication.conf`` allows one to specify credentials for
 
339
remote servers. This can be used for all the supported transports and any part
 
340
of bzr that requires authentication (smtp for example).
 
341
 
 
342
The syntax of the file obeys the same rules as the others except for the
 
343
variable policies which don't apply.
 
344
 
 
345
For more information on the possible uses of the authentication configuration
 
346
file see :doc:`authentication-help`.
 
347
 
 
348
 
 
349
Common variable options
 
350
-----------------------
 
351
 
 
352
debug_flags
 
353
~~~~~~~~~~~
 
354
 
 
355
A comma-separated list of debugging options to turn on.  The same values
 
356
can be used as with the -D command-line option (see `help global-options`).
 
357
For example::
 
358
 
 
359
    debug_flags = hpss
 
360
 
 
361
email
 
362
~~~~~
 
363
 
 
364
The email address to use when committing a branch. Typically takes the form
 
365
of::
 
366
 
 
367
    email = Full Name <account@hostname.tld>
 
368
 
 
369
editor
 
370
~~~~~~
 
371
 
 
372
The path of the editor that you wish to use if *bzr commit* is run without
 
373
a commit message. This setting is trumped by the environment variable
 
374
``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
 
375
variables.
 
376
 
 
377
log_format
 
378
~~~~~~~~~~
 
379
 
 
380
The default log format to use. Standard log formats are ``long``, ``short``
 
381
and ``line``. Additional formats may be provided by plugins. The default
 
382
value is ``long``.
 
383
 
 
384
check_signatures
 
385
~~~~~~~~~~~~~~~~
 
386
 
 
387
Defines the behavior for signatures.
 
388
 
 
389
require
 
390
    The gnupg signature for revisions must be present and must be valid.
 
391
 
 
392
ignore
 
393
    Do not check gnupg signatures of revisions.
 
394
 
 
395
check-available
 
396
    (default) If gnupg signatures for revisions are present, check them.
 
397
    Bazaar will fail if it finds a bad signature, but will not fail if
 
398
    no signature is present.
 
399
 
 
400
create_signatures
 
401
~~~~~~~~~~~~~~~~~
 
402
 
 
403
Defines the behaviour of signing revisions.
 
404
 
 
405
always
 
406
    Sign every new revision that is committed.
 
407
 
 
408
when-required
 
409
    (default) Sign newly committed revisions only when the branch requires
 
410
    signed revisions.
 
411
 
 
412
never
 
413
    Refuse to sign newly committed revisions, even if the branch
 
414
    requires signatures.
 
415
 
 
416
recurse
 
417
~~~~~~~
 
418
 
 
419
Only useful in ``locations.conf``. Defines whether or not the
 
420
configuration for this section applies to subdirectories:
 
421
 
 
422
true
 
423
    (default) This section applies to subdirectories as well.
 
424
 
 
425
false
 
426
    This section only applies to the branch at this directory and not
 
427
    branches below it.
 
428
 
 
429
gpg_signing_command
 
430
~~~~~~~~~~~~~~~~~~~
 
431
 
 
432
(Default: "gpg"). Which program should be used to sign and check revisions.
 
433
For example::
 
434
 
 
435
    gpg_signing_command = /usr/bin/gnpg
 
436
 
 
437
bzr_remote_path
 
438
~~~~~~~~~~~~~~~
 
439
 
 
440
(Default: "bzr").  The path to the command that should be used to run the smart
 
441
server for bzr.  This value may only be specified in locations.conf, because:
 
442
 
 
443
- it's needed before branch.conf is accessible
 
444
- allowing remote branch.conf files to specify commands would be a security
 
445
  risk
 
446
 
 
447
It is overridden by the BZR_REMOTE_PATH environment variable.
 
448
 
 
449
smtp_server
 
450
~~~~~~~~~~~
 
451
 
 
452
(Default: "localhost"). SMTP server to use when Bazaar needs to send
 
453
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
 
454
 
 
455
smtp_username, smtp_password
 
456
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
457
 
 
458
User and password to authenticate to the SMTP server. If smtp_username
 
459
is set, and smtp_password is not, Bazaar will prompt for a password.
 
460
These settings are only needed if the SMTP server requires authentication
 
461
to send mail.
 
462
 
 
463
mail_client
 
464
~~~~~~~~~~~
 
465
 
 
466
A mail client to use for sending merge requests.
 
467
By default, bzr will try to use ``mapi`` on Windows.  On other platforms, it
 
468
will try ``xdg-email``. If either of these fails, it will fall back to
 
469
``editor``.
 
470
 
 
471
Supported values for specific clients:
 
472
 
 
473
:claws: Use Claws.  This skips a dialog for attaching files.
 
474
:evolution: Use Evolution.
 
475
:kmail: Use KMail.
 
476
:mutt: Use Mutt.
 
477
:thunderbird: Use Mozilla Thunderbird or Icedove.  For Thunderbird/Icedove 1.5,
 
478
    this works around some bugs that xdg-email doesn't handle.
 
479
 
 
480
Supported generic values are:
 
481
 
 
482
:default: See above.
 
483
:editor: Use your editor to compose the merge request.  This also uses
 
484
    your commit id, (see ``bzr whoami``), smtp_server and (optionally)
 
485
    smtp_username and smtp_password.
 
486
:mapi: Use your preferred e-mail client on Windows.
 
487
:xdg-email: Use xdg-email to run your preferred mail program
 
488
 
 
489
submit_branch
 
490
~~~~~~~~~~~~~
 
491
 
 
492
The branch you intend to submit your current work to.  This is automatically
 
493
set by ``bzr send``, and is also used by the ``submit:`` revision spec.  This
 
494
should usually be set on a per-branch or per-location basis.
 
495
 
 
496
public_branch
 
497
~~~~~~~~~~~~~
 
498
 
 
499
A publically-accessible version of this branch (implying that this version is
 
500
not publically-accessible).  Used (and set) by ``bzr send``.
 
501
 
 
502
suppress_warnings
 
503
~~~~~~~~~~~~~~~~~
 
504
 
 
505
A list of strings, each string represent a warning that can be emitted by
 
506
bzr. Mentioning a warning in this list tells bzr to not emit it.
 
507
 
 
508
Valid values:
 
509
 
 
510
* ``format_deprecation``:
 
511
    whether the format deprecation warning is shown on repositories that are
 
512
    using deprecated formats.
 
513
 
 
514
default_format
 
515
~~~~~~~~~~~~~~
 
516
 
 
517
A format name for the default format used when creating branches.  See ``bzr
 
518
help formats`` for possible values.
 
519
 
 
520
 
 
521
Unicode options
 
522
---------------
 
523
 
 
524
output_encoding
 
525
~~~~~~~~~~~~~~~
 
526
 
 
527
A Python unicode encoding name for text output from bzr, such as log
 
528
information.  Values include: utf8, cp850, ascii, iso-8859-1.  The default
 
529
is the terminal encoding prefered by the operating system.
 
530
 
 
531
 
 
532
Branch type specific options
 
533
----------------------------
 
534
 
 
535
These options apply only to branches that use the ``dirstate-tags`` or
 
536
later format.  They
 
537
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
 
538
manually set in ``locations.conf`` or ``bazaar.conf``.
 
539
 
 
540
append_revisions_only
 
541
~~~~~~~~~~~~~~~~~~~~~
 
542
 
 
543
If set to "True" then revisions can only be appended to the log, not
 
544
removed.  A branch with this setting enabled can only pull from another
 
545
branch if the other branch's log is a longer version of its own.  This is
 
546
normally set by ``bzr init --append-revisions-only``. If you set it
 
547
manually, use either 'True' or 'False' (case-sensitive) to maintain
 
548
compatibility with previous bzr versions (older than 2.2).
 
549
 
 
550
parent_location
 
551
~~~~~~~~~~~~~~~
 
552
 
 
553
If present, the location of the default branch for pull or merge.
 
554
This option is normally set by ``pull --remember`` or ``merge
 
555
--remember``.
 
556
 
 
557
push_location
 
558
~~~~~~~~~~~~~
 
559
 
 
560
If present, the location of the default branch for push.  This option
 
561
is normally set by ``push --remember``.
 
562
 
 
563
push_strict
 
564
~~~~~~~~~~~
 
565
 
 
566
If present, defines the ``--strict`` option default value for checking
 
567
uncommitted changes before pushing.
 
568
 
 
569
dpush_strict
 
570
~~~~~~~~~~~~
 
571
 
 
572
If present, defines the ``--strict`` option default value for checking
 
573
uncommitted changes before pushing into a different VCS without any
 
574
custom bzr metadata.
 
575
 
 
576
bound_location
 
577
~~~~~~~~~~~~~~
 
578
 
 
579
The location that commits should go to when acting as a checkout.
 
580
This option is normally set by ``bind``.
 
581
 
 
582
bound
 
583
~~~~~
 
584
 
 
585
If set to "True", the branch should act as a checkout, and push each commit to
 
586
the bound_location.  This option is normally set by ``bind``/``unbind``.
 
587
 
 
588
send_strict
 
589
~~~~~~~~~~~
 
590
 
 
591
If present, defines the ``--strict`` option default value for checking
 
592
uncommitted changes before sending a merge directive.
 
593
 
 
594
 
 
595
External Merge Tools
 
596
--------------------
 
597
 
 
598
bzr.mergetool.<name>
 
599
~~~~~~~~~~~~~~~~~~~~
 
600
 
 
601
Defines an external merge tool called <name> with the given command-line.
 
602
Arguments containing spaces should be quoted using single or double quotes. The
 
603
executable may omit its path if it can be found on the PATH.
 
604
 
 
605
The following markers can be used in the command-line to substitute filenames
 
606
involved in the merge conflict:
 
607
 
 
608
{base}      file.BASE
 
609
{this}      file.THIS
 
610
{other}     file.OTHER
 
611
{result}    output file
 
612
{this_temp} temp copy of file.THIS, used to overwrite output file if merge
 
613
            succeeds.
 
614
 
 
615
For example:
 
616
 
 
617
  bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
618
 
 
619
bzr.default_mergetool
 
620
~~~~~~~~~~~~~~~~~
 
621
 
 
622
Specifies which external merge tool (as defined above) should be selected by
 
623
default in tools such as ``bzr qconflicts``.
 
624
 
 
625
For example:
 
626
 
 
627
  bzr.default_mergetool = kdiff3