← 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 16:58:03 UTC
  • mfrom: (3224.3.1 news-typo)
  • Revision ID: pqm@pqm.ubuntu.com-20080316165803-tisoc9mpob9z544o
(Matt Nordhoff) Trivial NEWS typo fix

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
 
14
18
 
15
19
  "John Doe <jdoe@example.com>"
16
20
 
17
 
See also the ``email`` configuration option.
 
21
See also the ``email`` configuration value.
18
22
 
19
23
BZR_PROGRESS_BAR
20
24
~~~~~~~~~~~~~~~~
21
25
 
22
 
Override the progress display.  Possible values are "none" or "text".  If
23
 
the value is "none" then no progress bar is displayed.  The value "text" draws
24
 
the ordinary command line progress bar.
 
26
Override the progress display.  Possible values are "none", "dots", "tty"
25
27
 
26
28
BZR_SIGQUIT_PDB
27
29
~~~~~~~~~~~~~~~
54
56
 
55
57
Path to the Bazaar executable to use when using the bzr+ssh protocol.
56
58
 
57
 
See also the ``bzr_remote_path`` configuration option.
 
59
See also the ``bzr_remote_path`` configuration value.
58
60
 
59
61
BZR_EDITOR
60
62
~~~~~~~~~~
61
63
 
62
64
Path to the editor Bazaar should use for commit messages, etc.
63
65
 
64
 
BZR_LOG
65
 
~~~~~~~
66
 
 
67
 
Location of the Bazaar log file. You can check the current location by
68
 
running ``bzr version``.
69
 
 
70
 
The log file contains debug information that is useful for diagnosing or
71
 
reporting problems with Bazaar.
72
 
 
73
 
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
74
 
will disable logging.
75
 
 
76
 
 
77
66
BZR_PLUGIN_PATH
78
67
~~~~~~~~~~~~~~~
79
68
 
80
69
The path to the plugins directory that Bazaar should use.
81
 
If not set, Bazaar will search for plugins in:
82
 
 
83
 
* the user specific plugin directory (containing the ``user`` plugins),
84
 
 
85
 
* the bzrlib directory (containing the ``core`` plugins),
86
 
 
87
 
* the site specific plugin directory if applicable (containing
88
 
  the ``site`` plugins).
89
 
 
90
 
If ``BZR_PLUGIN_PATH`` is set in any fashion, it will change the
91
 
the way the plugin are searched. 
92
 
 
93
 
As for the ``PATH`` variables, if multiple directories are
94
 
specified in ``BZR_PLUGIN_PATH`` they should be separated by the
95
 
platform specific appropriate character (':' on Unix,
96
 
';' on windows)
97
 
 
98
 
By default if ``BZR_PLUGIN_PATH`` is set, it replaces searching
99
 
in ``user``.  However it will continue to search in ``core`` and
100
 
``site`` unless they are explicitly removed.
101
 
 
102
 
If you need to change the order or remove one of these
103
 
directories, you should use special values:
104
 
 
105
 
* ``-user``, ``-core``, ``-site`` will remove the corresponding
106
 
  path from the default values,
107
 
 
108
 
* ``+user``, ``+core``, ``+site`` will add the corresponding path
109
 
  before the remaining default values (and also remove it from
110
 
  the default values).
111
 
 
112
 
Note that the special values 'user', 'core' and 'site' should be
113
 
used literally, they will be substituted by the corresponding,
114
 
platform specific, values.
115
 
 
116
 
The examples below use ':' as the separator, windows users
117
 
should use ';'.
118
 
 
119
 
Overriding the default user plugin directory::
120
 
 
121
 
  BZR_PLUGIN_PATH='/path/to/my/other/plugins'
122
 
 
123
 
Disabling the site directory while retaining the user directory::
124
 
 
125
 
  BZR_PLUGIN_PATH='-site:+user'
126
 
 
127
 
Disabling all plugins (better achieved with --no-plugins)::
128
 
 
129
 
  BZR_PLUGIN_PATH='-user:-core:-site'
130
 
 
131
 
Overriding the default site plugin directory::
132
 
 
133
 
  BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user
134
 
 
135
 
BZR_DISABLE_PLUGINS
136
 
~~~~~~~~~~~~~~~~~~~
137
 
 
138
 
Under special circumstances (mostly when trying to diagnose a
139
 
bug), it's better to disable a plugin (or several) rather than
140
 
uninstalling them completely. Such plugins can be specified in
141
 
the ``BZR_DISABLE_PLUGINS`` environment variable.
142
 
 
143
 
In that case, ``bzr`` will stop loading the specified plugins and
144
 
will raise an import error if they are explicitly imported (by
145
 
another plugin that depends on them for example).
146
 
 
147
 
Disabling ``myplugin`` and ``yourplugin`` is achieved by::
148
 
 
149
 
  BZR_DISABLE_PLUGINS='myplugin:yourplugin'
150
 
 
151
 
BZR_PLUGINS_AT
152
 
~~~~~~~~~~~~~~
153
 
 
154
 
When adding a new feature or working on a bug in a plugin,
155
 
developers often need to use a specific version of a given
156
 
plugin. Since python requires that the directory containing the
157
 
code is named like the plugin itself this make it impossible to
158
 
use arbitrary directory names (using a two-level directory scheme
159
 
is inconvenient). ``BZR_PLUGINS_AT`` allows such directories even
160
 
if they don't appear in ``BZR_PLUGIN_PATH`` .
161
 
 
162
 
Plugins specified in this environment variable takes precedence
163
 
over the ones in ``BZR_PLUGIN_PATH``.
164
 
 
165
 
The variable specified a list of ``plugin_name@plugin path``,
166
 
``plugin_name`` being the name of the plugin as it appears in
167
 
python module paths, ``plugin_path`` being the path to the
168
 
directory containing the plugin code itself
169
 
(i.e. ``plugins/myplugin`` not ``plugins``).  Use ':' as the list
170
 
separator, use ';' on windows.
171
 
 
172
 
Example:
173
 
~~~~~~~~
174
 
 
175
 
Using a specific version of ``myplugin``:
176
 
``BZR_PLUGINS_AT='myplugin@/home/me/bugfixes/123456-myplugin``
177
70
 
178
71
BZRPATH
179
72
~~~~~~~
181
74
The path where Bazaar should look for shell plugin external commands.
182
75
 
183
76
 
184
 
http_proxy, https_proxy
185
 
~~~~~~~~~~~~~~~~~~~~~~~
186
 
 
187
 
Specifies the network proxy for outgoing connections, for example::
188
 
 
189
 
  http_proxy=http://proxy.example.com:3128/ 
190
 
  https_proxy=http://proxy.example.com:3128/
191
 
 
192
 
 
193
77
Configuration files
194
78
-------------------
195
79
 
196
80
Location
197
81
~~~~~~~~
198
82
 
199
 
Configuration files are located in ``$HOME/.bazaar`` on Unix and
 
83
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
200
84
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
201
85
Windows. (You can check the location for your system by using
202
86
``bzr version``.)
238
122
 
239
123
    [DEFAULT]
240
124
 
241
 
The only valid section headers for bazaar.conf currently are [DEFAULT] and
242
 
[ALIASES].  Section headers are case sensitive. The default section provides for
243
 
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.
244
128
 
245
129
For ``locations.conf``, the variables from the section with the
246
130
longest matching section header are used to the exclusion of other
258
142
variable name, an equals sign and a value.  For example::
259
143
 
260
144
    email            = John Doe <jdoe@isp.com>
261
 
    gpg_signing_key  = Amy Pond <amy@example.com>
262
 
 
263
 
A variable can reference other variables **in the same configuration file** by
264
 
enclosing them in curly brackets::
265
 
 
266
 
    my_branch_name = feature_x
267
 
    my_server      = bzr+ssh://example.com
268
 
    push_location   = {my_server}/project/{my_branch_name}
 
145
    check_signatures = require
269
146
 
270
147
 
271
148
Variable policies
301
178
The main configuration file, bazaar.conf
302
179
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
303
180
 
304
 
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
305
 
The default section contains the default
 
181
``bazaar.conf`` only allows one
 
182
section called ``[DEFAULT]``. This default section contains the default
306
183
configuration options for all branches. The default section can be
307
184
overriden by providing a branch-specific section in ``locations.conf``.
308
185
 
311
188
    [DEFAULT]
312
189
    email             = John Doe <jdoe@isp.com>
313
190
    editor            = /usr/bin/vim
 
191
    check_signatures  = check-available
314
192
    create_signatures = when-required
315
193
 
316
194
 
328
206
 
329
207
    [http://hypothetical.site.com/branches/devel-branch]
330
208
    create_signatures = always
 
209
    check_signatures  = always
 
210
 
 
211
    [http://bazaar-vcs.org/bzr/*]
 
212
    check_signatures  = require
331
213
 
332
214
The authentication configuration file, authentication.conf
333
215
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340
222
variable policies which don't apply.
341
223
 
342
224
For more information on the possible uses of the authentication configuration
343
 
file see :doc:`authentication-help`.
 
225
file see `Authentication Settings`_.
344
226
 
345
227
 
346
228
Common variable options
347
229
-----------------------
348
230
 
349
 
debug_flags
350
 
~~~~~~~~~~~
351
 
 
352
 
A comma-separated list of debugging options to turn on.  The same values
353
 
can be used as with the -D command-line option (see `help global-options`).
354
 
For example::
355
 
 
356
 
    debug_flags = hpss
357
 
 
358
 
or::
359
 
 
360
 
    debug_flags = hpss,evil
361
 
 
362
231
email
363
232
~~~~~
364
233
 
375
244
``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
376
245
variables.
377
246
 
378
 
log_format
379
 
~~~~~~~~~~
380
 
 
381
 
The default log format to use. Standard log formats are ``long``, ``short``
382
 
and ``line``. Additional formats may be provided by plugins. The default
383
 
value is ``long``.
384
 
 
385
247
check_signatures
386
248
~~~~~~~~~~~~~~~~
387
249
 
388
 
Reserved for future use.  These options will allow a policy for branches to
389
 
require signatures.
 
250
Defines the behavior for signatures.
390
251
 
391
252
require
392
253
    The gnupg signature for revisions must be present and must be valid.
402
263
create_signatures
403
264
~~~~~~~~~~~~~~~~~
404
265
 
405
 
Defines the behaviour of signing revisions on commits.  By default bzr will not
406
 
sign new commits.
 
266
Defines the behaviour of signing revisions.
407
267
 
408
268
always
409
 
    Sign every new revision that is committed.  If the signing fails then the
410
 
    commit will not be made.
 
269
    Sign every new revision that is committed.
411
270
 
412
271
when-required
413
 
    Reserved for future use.
 
272
    (default) Sign newly committed revisions only when the branch requires
 
273
    signed revisions.
414
274
 
415
275
never
416
 
    Reserved for future use.
417
 
 
418
 
In future it is planned that ``when-required`` will sign newly
419
 
committed revisions only when the branch requires them.  ``never`` will refuse
420
 
to sign newly committed revisions, even if the branch requires signatures.
421
 
 
422
 
dirstate.fdatasync
423
 
~~~~~~~~~~~~~~~~~~
424
 
 
425
 
If true (default), working tree metadata changes are flushed through the
426
 
OS buffers to physical disk.  This is somewhat slower, but means data
427
 
should not be lost if the machine crashes.  See also repository.fdatasync.
428
 
 
429
 
gpg_signing_key
430
 
~~~~~~~~~~~~~~~
431
 
 
432
 
The GnuPG user identity to use when signing commits.  Can be an e-mail
433
 
address, key fingerprint or full key ID.  When unset or when set to
434
 
"default" Bazaar will use the user e-mail set with ``whoami``.
 
276
    Refuse to sign newly committed revisions, even if the branch
 
277
    requires signatures.
435
278
 
436
279
recurse
437
280
~~~~~~~
454
297
 
455
298
    gpg_signing_command = /usr/bin/gnpg
456
299
 
457
 
The specified command must accept the options "--clearsign" and "-u <email>".
458
 
 
459
300
bzr_remote_path
460
301
~~~~~~~~~~~~~~~
461
302
 
482
323
These settings are only needed if the SMTP server requires authentication
483
324
to send mail.
484
325
 
485
 
locks.steal_dead
486
 
~~~~~~~~~~~~~~~~
487
 
 
488
 
If set to true, bzr will automatically break locks held by processes from
489
 
the same machine and user that are no longer alive.  Otherwise, it will
490
 
print a message and you can break the lock manually, if you are satisfied
491
 
the object is no longer in use.
492
 
 
493
326
mail_client
494
327
~~~~~~~~~~~
495
328
 
500
333
 
501
334
Supported values for specific clients:
502
335
 
503
 
:claws: Use Claws.  This skips a dialog for attaching files.
504
336
:evolution: Use Evolution.
505
337
:kmail: Use KMail.
506
338
:mutt: Use Mutt.
516
348
:mapi: Use your preferred e-mail client on Windows.
517
349
:xdg-email: Use xdg-email to run your preferred mail program
518
350
 
519
 
repository.fdatasync
520
 
~~~~~~~~~~~~~~~~~~~~
521
 
 
522
 
If true (default), repository changes are flushed through the OS buffers
523
 
to physical disk.  This is somewhat slower, but means data should not be
524
 
lost if the machine crashes.  See also dirstate.fdatasync.
525
 
 
526
351
submit_branch
527
352
~~~~~~~~~~~~~
528
353
 
536
361
A publically-accessible version of this branch (implying that this version is
537
362
not publically-accessible).  Used (and set) by ``bzr send``.
538
363
 
539
 
suppress_warnings
540
 
~~~~~~~~~~~~~~~~~
541
 
 
542
 
A list of strings, each string represent a warning that can be emitted by
543
 
bzr. Mentioning a warning in this list tells bzr to not emit it.
544
 
 
545
 
Valid values:
546
 
 
547
 
* ``format_deprecation``:
548
 
    whether the format deprecation warning is shown on repositories that are
549
 
    using deprecated formats.
550
 
 
551
 
default_format
552
 
~~~~~~~~~~~~~~
553
 
 
554
 
A format name for the default format used when creating branches.  See ``bzr
555
 
help formats`` for possible values.
556
 
 
557
 
 
558
 
Unicode options
559
 
---------------
560
 
 
561
 
output_encoding
562
 
~~~~~~~~~~~~~~~
563
 
 
564
 
A Python unicode encoding name for text output from bzr, such as log
565
 
information.  Values include: utf8, cp850, ascii, iso-8859-1.  The default
566
 
is the terminal encoding prefered by the operating system.
567
 
 
568
364
 
569
365
Branch type specific options
570
366
----------------------------
578
374
~~~~~~~~~~~~~~~~~~~~~
579
375
 
580
376
If set to "True" then revisions can only be appended to the log, not
581
 
removed.  A branch with this setting enabled can only pull from another
582
 
branch if the other branch's log is a longer version of its own.  This is
583
 
normally set by ``bzr init --append-revisions-only``. If you set it
584
 
manually, use either 'True' or 'False' (case-sensitive) to maintain
585
 
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``.
586
380
 
587
381
parent_location
588
382
~~~~~~~~~~~~~~~
589
383
 
590
 
If present, the location of the default branch for pull or merge.  This option
591
 
is normally set when creating a branch, the first ``pull`` or by ``pull
 
384
If present, the location of the default branch for pull or merge.
 
385
This option is normally set by ``pull --remember`` or ``merge
592
386
--remember``.
593
387
 
594
388
push_location
595
389
~~~~~~~~~~~~~
596
390
 
597
391
If present, the location of the default branch for push.  This option
598
 
is normally set by the first ``push`` or ``push --remember``.
599
 
 
600
 
push_strict
601
 
~~~~~~~~~~~
602
 
 
603
 
If present, defines the ``--strict`` option default value for checking
604
 
uncommitted changes before pushing.
605
 
 
606
 
dpush_strict
607
 
~~~~~~~~~~~~
608
 
 
609
 
If present, defines the ``--strict`` option default value for checking
610
 
uncommitted changes before pushing into a different VCS without any
611
 
custom bzr metadata.
 
392
is normally set by ``push --remember``.
612
393
 
613
394
bound_location
614
395
~~~~~~~~~~~~~~
621
402
 
622
403
If set to "True", the branch should act as a checkout, and push each commit to
623
404
the bound_location.  This option is normally set by ``bind``/``unbind``.
624
 
 
625
 
send_strict
626
 
~~~~~~~~~~~
627
 
 
628
 
If present, defines the ``--strict`` option default value for checking
629
 
uncommitted changes before sending a merge directive.
630
 
 
631
 
add.maximum_file_size
632
 
~~~~~~~~~~~~~~~~~~~~~
633
 
 
634
 
Defines the maximum file size the command line "add" operation will allow
635
 
in recursive mode, with files larger than this value being skipped. You may 
636
 
specify this value as an integer (in which case it is interpreted as bytes), 
637
 
or you may specify the value using SI units, i.e. 10KB, 20MB, 1G. A value of 0 
638
 
will disable skipping.
639
 
 
640
 
External Merge Tools
641
 
--------------------
642
 
 
643
 
bzr.mergetool.<name>
644
 
~~~~~~~~~~~~~~~~~~~~
645
 
 
646
 
Defines an external merge tool called <name> with the given command-line.
647
 
Arguments containing spaces should be quoted using single or double quotes. The
648
 
executable may omit its path if it can be found on the PATH.
649
 
 
650
 
The following markers can be used in the command-line to substitute filenames
651
 
involved in the merge conflict::
652
 
 
653
 
  {base}      file.BASE
654
 
  {this}      file.THIS
655
 
  {other}     file.OTHER
656
 
  {result}    output file
657
 
  {this_temp} temp copy of file.THIS, used to overwrite output file if merge
658
 
              succeeds.
659
 
 
660
 
For example::
661
 
 
662
 
  bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
663
 
 
664
 
bzr.default_mergetool
665
 
~~~~~~~~~~~~~~~~~~~~~
666
 
 
667
 
Specifies which external merge tool (as defined above) should be selected by
668
 
default in tools such as ``bzr qconflicts``.
669
 
 
670
 
For example::
671
 
 
672
 
  bzr.default_mergetool = kdiff3