7
7
While most configuration is handled by configuration files, some options
8
8
which may be semi-permanent can also be controlled through the environment.
13
Override the email id used by Breezy. Typical format::
13
Override the email id used by Bazaar. Typical format::
15
15
"John Doe <jdoe@example.com>"
17
See also the ``email`` configuration option.
17
See also the ``email`` configuration value.
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.
22
Override the progress display. Possible values are "none", "dots", "tty"
29
27
Control whether SIGQUIT behaves normally or invokes a breakin debugger.
31
29
* 0 = Standard SIGQUIT behavior (normally, exit with a core dump)
32
30
* 1 = Invoke breakin debugger (default)
37
Override the home directory used by Breezy.
35
Override the home directory used by Bazaar.
42
40
Select a different SSH implementation.
47
45
Control whether to launch a debugger on error.
55
Path to the Bazaar or Breezy executable to use when using the bzr+ssh protocol.
57
See also the ``bzr_remote_path`` configuration option.
53
Path to the Bazaar executable to use when using the bzr+ssh protocol.
55
See also the ``bzr_remote_path`` configuration value.
62
Path to the editor Breezy should use for commit messages, etc.
60
Path to the editor Bazaar should use for commit messages, etc.
67
Location of the Breezy log file. You can check the current location by
65
Location of the Bazaar log file. You can check the current location by
68
66
running ``bzr version``.
70
68
The log file contains debug information that is useful for diagnosing or
71
reporting problems with Breezy.
69
reporting problems with Bazaar.
73
71
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
74
72
will disable logging.
80
The path to the plugins directory that Breezy should use.
81
If not set, Breezy will search for plugins in:
78
The path to the plugins directory that Bazaar should use.
79
If not set, Bazaar will search for plugins in:
83
81
* the user specific plugin directory (containing the ``user`` plugins),
85
* the breezy directory (containing the ``core`` plugins),
83
* the bzrlib directory (containing the ``core`` plugins),
87
85
* the site specific plugin directory if applicable (containing
88
86
the ``site`` plugins).
199
197
Configuration files are located in ``$HOME/.bazaar`` on Unix and
200
``C:\Documents and Settings\<username>\Application Data\Breezy\2.0`` on
198
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
201
199
Windows. (You can check the location for your system by using
202
200
``bzr version``.)
204
202
There are three primary configuration files in this location:
206
* ``breezy.conf`` describes default configuration options,
204
* ``bazaar.conf`` describes default configuration options,
208
206
* ``locations.conf`` describes configuration information for
209
207
specific branch locations,
223
221
An ini file has three types of contructs: section headers, section
224
options and comments.
222
variables and comments.
229
227
A comment is any line that starts with a "#" (sometimes called a "hash
230
228
mark", "pound sign" or "number sign"). Comment lines are ignored by
231
Breezy when parsing ini files.
229
Bazaar when parsing ini files.
241
The only valid section headers for breezy.conf currently are [DEFAULT] and
239
The only valid section headers for bazaar.conf currently are [DEFAULT] and
242
240
[ALIASES]. Section headers are case sensitive. The default section provides for
243
setting options which can be overridden with the branch config file.
241
setting variables which can be overridden with the branch config file.
245
For ``locations.conf``, the options from the section with the
243
For ``locations.conf``, the variables from the section with the
246
244
longest matching section header are used to the exclusion of other
247
245
potentially valid section headers. A section header uses the path for
248
246
the branch as the section header. Some examples include::
251
249
[/home/jdoe/branches/]
257
A section option resides within a section. A section option contains an
258
option name, an equals sign and a value. For example::
255
A section variable resides within a section. A section variable contains a
256
variable name, an equals sign and a value. For example::
260
258
email = John Doe <jdoe@isp.com>
261
gpg_signing_key = Amy Pond <amy@example.com>
263
A option can reference other options by enclosing them in curly brackets::
265
my_branch_name = feature_x
266
my_server = bzr+ssh://example.com
267
push_location = {my_server}/project/{my_branch_name}
272
Options defined in a section affect the named directory or URL plus
273
any locations they contain. Policies can be used to change how an
274
option value is interpreted for contained locations. Currently
259
check_signatures = require
265
Variables defined in a section affect the named directory or URL plus
266
any locations they contain. Policies can be used to change how a
267
variable value is interpreted for contained locations. Currently
275
268
there are three policies available:
284
277
for contained locations, any additional path components are
285
278
appended to the value.
287
Policies are specified by keys with names of the form "<option_name>:policy".
280
Policies are specified by keys with names of the form "$var:policy".
288
281
For example, to define the push location for a tree of branches, the
289
282
following could be used::
295
288
With this configuration, the push location for ``/top/location/branch1``
296
289
would be ``sftp://example.com/location/branch1``.
298
Section local options
299
^^^^^^^^^^^^^^^^^^^^^
301
Some options are defined automatically inside a given section and can be
302
refered to in this section only.
304
For example, the ``appendpath`` policy can be used like this::
306
[/home/vila/src/bzr/bugs]
307
mypush = lp:~vila/bzr
308
mypush:policy=appendpath
310
Using ``relpath`` to achieve the same result is done like this::
312
[/home/vila/src/bzr/bugs]
313
mypush = lp:~vila/bzr/{relpath}
315
In both cases, when used in a directory like
316
``/home/vila/src/bzr/bugs/832013-expand-in-stack`` we'll get::
319
lp:~vila/bzr/832013-expand-in-stack
321
Another such option is ``basename`` which can be used like this::
324
mypush = lp:~vila/bzr/{basename}
326
When used in a directory like
327
``/home/vila/src/bzr/bugs/832013-expand-in-stack`` we'll get::
330
lp:~vila/bzr/832013-expand-in-stack
332
Note that ``basename`` here refers to the base name of ``relpath`` which
333
itself is defined as the relative path between the section name and the
336
Another such option is ``branchname``, which refers to the name of a colocated
337
branch. For non-colocated branches, it behaves like basename. It can be used
340
[/home/vila/src/bzr/bugs]
341
mypush = lp:~vila/bzr/{branchname}
343
When used with a colocated branch named ``832013-expand-in-stack``, we'll get::
346
lp:~vila/bzr/832013-expand-in-stack
348
When an option is local to a Section, it cannot be referred to from option
349
values in any other section from the same ``Store`` nor from any other
353
The main configuration file, breezy.conf
292
The main configuration file, bazaar.conf
354
293
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
356
``breezy.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
295
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
357
296
The default section contains the default
358
297
configuration options for all branches. The default section can be
359
298
overriden by providing a branch-specific section in ``locations.conf``.
361
A typical ``breezy.conf`` section often looks like the following::
300
A typical ``bazaar.conf`` section often looks like the following::
364
303
email = John Doe <jdoe@isp.com>
365
304
editor = /usr/bin/vim
305
check_signatures = check-available
366
306
create_signatures = when-required
372
312
``locations.conf`` allows one to specify overriding settings for
373
313
a specific branch. The format is almost identical to the default section in
374
breezy.conf with one significant change: The section header, instead of saying
314
bazaar.conf with one significant change: The section header, instead of saying
375
315
default, will be the path to a branch that you wish to override a value
376
316
for. The '?' and '*' wildcards are supported::
381
321
[http://hypothetical.site.com/branches/devel-branch]
382
322
create_signatures = always
323
check_signatures = always
325
[http://bazaar-vcs.org/bzr/*]
326
check_signatures = require
384
328
The authentication configuration file, authentication.conf
385
329
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
389
333
of bzr that requires authentication (smtp for example).
391
335
The syntax of the file obeys the same rules as the others except for the
392
option policies which don't apply.
336
variable policies which don't apply.
394
338
For more information on the possible uses of the authentication configuration
395
339
file see :doc:`authentication-help`.
342
Common variable options
343
-----------------------
450
389
(default) If gnupg signatures for revisions are present, check them.
451
Breezy will fail if it finds a bad signature, but will not fail if
390
Bazaar will fail if it finds a bad signature, but will not fail if
452
391
no signature is present.
454
393
create_signatures
455
394
~~~~~~~~~~~~~~~~~
457
Defines the behaviour of signing revisions on commits. By default bzr will not
396
Defines the behaviour of signing revisions.
461
Sign every new revision that is committed. If the signing fails then the
462
commit will not be made.
399
Sign every new revision that is committed.
465
Reserved for future use.
402
(default) Sign newly committed revisions only when the branch requires
468
Reserved for future use.
470
In future it is planned that ``when-required`` will sign newly
471
committed revisions only when the branch requires them. ``never`` will refuse
472
to sign newly committed revisions, even if the branch requires signatures.
477
If true (default), working tree metadata changes are flushed through the
478
OS buffers to physical disk. This is somewhat slower, but means data
479
should not be lost if the machine crashes. See also repository.fdatasync.
484
The GnuPG user identity to use when signing commits. Can be an e-mail
485
address, key fingerprint or full key ID. When unset or when set to
486
"default" Breezy will use the user e-mail set with ``whoami``.
406
Refuse to sign newly committed revisions, even if the branch
516
(Default: "localhost"). SMTP server to use when Breezy needs to send
445
(Default: "localhost"). SMTP server to use when Bazaar needs to send
517
446
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
519
448
smtp_username, smtp_password
520
449
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
522
451
User and password to authenticate to the SMTP server. If smtp_username
523
is set, and smtp_password is not, Breezy will prompt for a password.
452
is set, and smtp_password is not, Bazaar will prompt for a password.
524
453
These settings are only needed if the SMTP server requires authentication
530
By default, bzr will automatically break locks held by processes from
531
the same machine and user that are no longer alive. If disabled, it will
532
print a message and you can break the lock manually, if you are satisfied
533
the object is no longer in use.
558
479
:mapi: Use your preferred e-mail client on Windows.
559
480
:xdg-email: Use xdg-email to run your preferred mail program
564
If true (default), repository changes are flushed through the OS buffers
565
to physical disk. This is somewhat slower, but means data should not be
566
lost if the machine crashes. See also dirstate.fdatasync.
590
504
whether the format deprecation warning is shown on repositories that are
591
505
using deprecated formats.
593
* ``insecure_permissions``:
594
whether a warning is shown if ``authentication.conf`` can be read
600
A format name for the default format used when creating branches. See ``bzr
601
help formats`` for possible values.
636
If present, the location of the default branch for pull or merge. This option
637
is normally set when creating a branch, the first ``pull`` or by ``pull
540
If present, the location of the default branch for pull or merge.
541
This option is normally set by ``pull --remember`` or ``merge
643
547
If present, the location of the default branch for push. This option
644
is normally set by the first ``push`` or ``push --remember``.
548
is normally set by ``push --remember``.
667
578
If present, defines the ``--strict`` option default value for checking
668
579
uncommitted changes before sending a merge directive.
670
add.maximum_file_size
671
~~~~~~~~~~~~~~~~~~~~~
673
Defines the maximum file size the command line "add" operation will allow
674
in recursive mode, with files larger than this value being skipped. You may
675
specify this value as an integer (in which case it is interpreted as bytes),
676
or you may specify the value using SI units, i.e. 10KB, 20MB, 1G. A value of 0
677
will disable skipping.
685
Defines an external merge tool called <name> with the given command-line.
686
Arguments containing spaces should be quoted using single or double quotes. The
687
executable may omit its path if it can be found on the PATH.
689
The following markers can be used in the command-line to substitute filenames
690
involved in the merge conflict::
696
{this_temp} temp copy of file.THIS, used to overwrite output file if merge
701
bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
703
Because ``mergetool`` and ``config`` itself both use curly braces as
704
interpolation markers, trying to display the mergetool line results in the
708
$ bzr config bzr.mergetool.kdiff3='kdiff3 {base} {this} {other} -o {result}'
709
$ bzr config bzr.mergetool.kdiff3
710
bzr: ERROR: Option base is not defined while expanding "kdiff3 {base} {this} {other} -o {result}".
712
To avoid this, ``config`` can be instructed not to try expanding variables::
714
$ bzr config --all bzr.mergetool.kdiff3
716
bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
719
bzr.default_mergetool
720
~~~~~~~~~~~~~~~~~~~~~
722
Specifies which external merge tool (as defined above) should be selected by
723
default in tools such as ``bzr qconflicts``.
727
bzr.default_mergetool = kdiff3