← 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: Patch Queue Manager
  • Date: 2011-10-14 16:54:26 UTC
  • mfrom: (6216.1.1 remove-this-file)
  • Revision ID: pqm@pqm.ubuntu.com-20111014165426-tjix4e6idryf1r2z
(jelmer) Remove an accidentally committed .THIS file. (Jelmer Vernooij)

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
 
 
8
4
Environment settings
9
5
---------------------
10
6
 
18
14
 
19
15
  "John Doe <jdoe@example.com>"
20
16
 
21
 
See also the ``email`` configuration value.
 
17
See also the ``email`` configuration option.
22
18
 
23
19
BZR_PROGRESS_BAR
24
20
~~~~~~~~~~~~~~~~
25
21
 
26
 
Override the progress display.  Possible values are "none", "dots", "tty"
 
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.
27
25
 
28
26
BZR_SIGQUIT_PDB
29
27
~~~~~~~~~~~~~~~
56
54
 
57
55
Path to the Bazaar executable to use when using the bzr+ssh protocol.
58
56
 
59
 
See also the ``bzr_remote_path`` configuration value.
 
57
See also the ``bzr_remote_path`` configuration option.
60
58
 
61
59
BZR_EDITOR
62
60
~~~~~~~~~~
63
61
 
64
62
Path to the editor Bazaar should use for commit messages, etc.
65
63
 
 
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
 
66
77
BZR_PLUGIN_PATH
67
78
~~~~~~~~~~~~~~~
68
79
 
69
80
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``
70
177
 
71
178
BZRPATH
72
179
~~~~~~~
74
181
The path where Bazaar should look for shell plugin external commands.
75
182
 
76
183
 
 
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
 
77
193
Configuration files
78
194
-------------------
79
195
 
80
196
Location
81
197
~~~~~~~~
82
198
 
83
 
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
 
199
Configuration files are located in ``$HOME/.bazaar`` on Unix and
84
200
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
85
201
Windows. (You can check the location for your system by using
86
202
``bzr version``.)
122
238
 
123
239
    [DEFAULT]
124
240
 
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.
 
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.
128
244
 
129
245
For ``locations.conf``, the variables from the section with the
130
246
longest matching section header are used to the exclusion of other
142
258
variable name, an equals sign and a value.  For example::
143
259
 
144
260
    email            = John Doe <jdoe@isp.com>
145
 
    check_signatures = require
 
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}
146
269
 
147
270
 
148
271
Variable policies
178
301
The main configuration file, bazaar.conf
179
302
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180
303
 
181
 
``bazaar.conf`` only allows one
182
 
section called ``[DEFAULT]``. This default section contains the default
 
304
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
 
305
The default section contains the default
183
306
configuration options for all branches. The default section can be
184
307
overriden by providing a branch-specific section in ``locations.conf``.
185
308
 
188
311
    [DEFAULT]
189
312
    email             = John Doe <jdoe@isp.com>
190
313
    editor            = /usr/bin/vim
191
 
    check_signatures  = check-available
192
314
    create_signatures = when-required
193
315
 
194
316
 
206
328
 
207
329
    [http://hypothetical.site.com/branches/devel-branch]
208
330
    create_signatures = always
209
 
    check_signatures  = always
210
 
 
211
 
    [http://bazaar-vcs.org/bzr/*]
212
 
    check_signatures  = require
213
331
 
214
332
The authentication configuration file, authentication.conf
215
333
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
222
340
variable policies which don't apply.
223
341
 
224
342
For more information on the possible uses of the authentication configuration
225
 
file see `Authentication Settings`_.
 
343
file see :doc:`authentication-help`.
226
344
 
227
345
 
228
346
Common variable options
229
347
-----------------------
230
348
 
 
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
 
231
362
email
232
363
~~~~~
233
364
 
244
375
``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
245
376
variables.
246
377
 
 
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
 
247
385
check_signatures
248
386
~~~~~~~~~~~~~~~~
249
387
 
250
 
Defines the behavior for signatures.
 
388
Reserved for future use.  These options will allow a policy for branches to
 
389
require signatures.
251
390
 
252
391
require
253
392
    The gnupg signature for revisions must be present and must be valid.
263
402
create_signatures
264
403
~~~~~~~~~~~~~~~~~
265
404
 
266
 
Defines the behaviour of signing revisions.
 
405
Defines the behaviour of signing revisions on commits.  By default bzr will not
 
406
sign new commits.
267
407
 
268
408
always
269
 
    Sign every new revision that is committed.
 
409
    Sign every new revision that is committed.  If the signing fails then the
 
410
    commit will not be made.
270
411
 
271
412
when-required
272
 
    (default) Sign newly committed revisions only when the branch requires
273
 
    signed revisions.
 
413
    Reserved for future use.
274
414
 
275
415
never
276
 
    Refuse to sign newly committed revisions, even if the branch
277
 
    requires signatures.
 
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``.
278
435
 
279
436
recurse
280
437
~~~~~~~
297
454
 
298
455
    gpg_signing_command = /usr/bin/gnpg
299
456
 
 
457
The specified command must accept the options "--clearsign" and "-u <email>".
 
458
 
300
459
bzr_remote_path
301
460
~~~~~~~~~~~~~~~
302
461
 
323
482
These settings are only needed if the SMTP server requires authentication
324
483
to send mail.
325
484
 
 
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
 
326
493
mail_client
327
494
~~~~~~~~~~~
328
495
 
333
500
 
334
501
Supported values for specific clients:
335
502
 
 
503
:claws: Use Claws.  This skips a dialog for attaching files.
336
504
:evolution: Use Evolution.
337
505
:kmail: Use KMail.
338
506
:mutt: Use Mutt.
348
516
:mapi: Use your preferred e-mail client on Windows.
349
517
:xdg-email: Use xdg-email to run your preferred mail program
350
518
 
 
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
 
351
526
submit_branch
352
527
~~~~~~~~~~~~~
353
528
 
361
536
A publically-accessible version of this branch (implying that this version is
362
537
not publically-accessible).  Used (and set) by ``bzr send``.
363
538
 
 
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
 
364
568
 
365
569
Branch type specific options
366
570
----------------------------
374
578
~~~~~~~~~~~~~~~~~~~~~
375
579
 
376
580
If set to "True" then revisions can only be appended to the log, not
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``.
 
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).
380
586
 
381
587
parent_location
382
588
~~~~~~~~~~~~~~~
383
589
 
384
 
If present, the location of the default branch for pull or merge.
385
 
This option is normally set by ``pull --remember`` or ``merge
 
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
386
592
--remember``.
387
593
 
388
594
push_location
389
595
~~~~~~~~~~~~~
390
596
 
391
597
If present, the location of the default branch for push.  This option
392
 
is normally set by ``push --remember``.
 
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.
393
612
 
394
613
bound_location
395
614
~~~~~~~~~~~~~~
402
621
 
403
622
If set to "True", the branch should act as a checkout, and push each commit to
404
623
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