5
Information on how to configure Bazaar.
7
.. TODO: Should have some explanation of why you'd want things in
13
While most configuration is handled by configuration files, some options
14
which may be semi-permanent can also be controlled through the environment.
18
Override the email id used by Bazaar. Typical format::
20
"John Doe <jdoe@example.com>"
22
See also the ``email`` configuration value.
26
Override the progress display. Possible values are "none", "dots", "tty"
30
Control whether SIGQUIT behaves normally or invokes a breakin debugger.
31
0 = Standard SIGQUIT behavior
32
1 = Invoke breakin debugger (default)
36
Override the home directory used by Bazaar.
40
Select a different SSH implementation.
44
Control whether to launch a debugger on error.
50
Path to the Bazaar executable to use when using the bzr+ssh protocol.
52
See also the ``bzr_remote_path`` configuration value
56
Path to the editor Bazaar should use for commit messages, etc.
60
The path to the plugins directory that Bazaar should use.
64
The path where Bazaar should look for shell plugin external commands.
67
Location of configuration files
68
===============================
69
Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first
70
one, named ``bazaar.conf``, includes default configuration options. The other
71
file, ``locations.conf``, contains configuration information for specific
72
branch locations. These files are sometimes referred to as ``ini files``.
74
Each branch can also contain a configuration file that sets values specific
75
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
76
branch. This file is visible to all users of a branch, if you wish to override
77
one of the values for a branch with a setting that is specific to you then you
78
can do so in ``locations.conf``.
82
An ini file has three types of contructs: section headers, section
83
variables and comments.
87
A comment is any line that starts with a "#" (sometimes called a "hash
88
mark", "pound sign" or "number sign"). Comment lines are ignored by
89
Bazaar when parsing ini files.
93
A section header is a word enclosed in brackets that starts at the begining
94
of a line. A typical section header looks like this::
98
The only valid section header for bazaar.conf is [DEFAULT], which is
99
case sensitive. The default section provides for setting variables
100
which can be overridden with the branch config file.
102
For ``locations.conf``, the variables from the section with the
103
longest matching section header are used to the exclusion of other
104
potentially valid section headers. A section header uses the path for
105
the branch as the section header. Some examples include::
107
[http://mybranches.isp.com/~jdoe/branchdir]
108
[/home/jdoe/branches/]
114
A section variable resides within a section. A section variable contains a
115
variable name, an equals sign and a value. For example::
117
email = John Doe <jdoe@isp.com>
118
check_signatures = require
124
Variables defined in a section affect the named directory or URL plus
125
any locations they contain. Policies can be used to change how a
126
variable value is interpreted for contained locations. Currently
127
there are three policies available:
130
the value is interpreted the same for contained locations. This is
131
the default behaviour.
133
the value is only used for the exact location specified by the
136
for contained locations, any additional path components are
137
appended to the value.
139
Policies are specified by keys with names of the form "$var:policy".
140
For example, to define the push location for a tree of branches, the
141
following could be used::
144
push_location = sftp://example.com/location
145
push_location:policy = appendpath
147
With this configuration, the push location for ``/top/location/branch1``
148
would be ``sftp://example.com/location/branch1``.
151
The main configuration file, bazaar.conf
152
----------------------------------------
154
The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one
155
section called ``[DEFAULT]``. This default section contains the default
156
configuration options for all branches. The default section can be
157
overriden by providing a branch-specific section in ``locations.conf``.
159
A typical ``bazaar.conf`` section often looks like the following::
162
email = John Doe <jdoe@isp.com>
163
editor = /usr/bin/vim
164
check_signatures = check-available
165
create_signatures = when-required
167
``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for a
168
specific branch. The format is almost identical to the default section in
169
bazaar.conf with one significant change: The section header, instead of
170
saying default, will be the path to a branch that you wish to override a
171
value for. The '?' and '*' wildcards are supported::
173
[/home/jdoe/branches/nethack]
174
email = Nethack Admin <nethack@nethack.com>
176
[http://hypothetical.site.com/branches/devel-branch]
177
create_signatures = always
178
check_signatures = always
180
[http://bazaar-vcs.org/bzr/*]
181
check_signatures = require
183
Common Variable Options
184
=======================
188
The email address to use when committing a branch. Typically takes the form
191
email = Full Name <account@hostname.tld>
195
The path of the editor that you wish to use if *bzr commit* is run without
196
a commit message. This setting is trumped by the environment variable
197
``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.
201
Defines the behavior for signatures.
204
The gnupg signature for revisions must be present and must be valid.
207
Do not check gnupg signatures of revisions.
210
(default) If gnupg signatures for revisions are present, check them.
211
Bazaar will fail if it finds a bad signature, but will not fail if
212
no signature is present.
216
Defines the behaviour of signing revisions.
219
Sign every new revision that is committed.
222
(default) Sign newly committed revisions only when the branch requires
226
Refuse to sign newly committed revisions, even if the branch
231
Only useful in ``locations.conf``. Defines whether or not the
232
configuration for this section applies to subdirectories:
235
(default) This section applies to subdirectories as well.
238
This section only applies to the branch at this directory and not
243
(Default: "gpg"). Which program should be used to sign and check revisions.
246
gpg_signing_command = /usr/bin/gnpg
250
(Default: "bzr"). The path to the command that should be used to run the smart
251
server for bzr. This value may only be specified in locations.conf, because:
253
- it's needed before branch.conf is accessible
254
- allowing remote branch.conf files to specify commands would be a security
257
It is overridden by the BZR_REMOTE_PATH environment variable.
261
(Default: "localhost"). SMTP server to use when Bazaar needs to send
262
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
264
smtp_username, smtp_password
265
----------------------------
266
User and password to authenticate to the SMTP server. If smtp_username
267
is set, and smtp_password is not, Bazaar will prompt for a password.
268
These settings are only needed if the SMTP server requires authentication
273
A mail client to use for sending merge requests.
274
By default, bzr will try to use ``mapi`` on Windows. On other platforms, it
275
will try ``xdg-email``. If either of these fails, it will fall back to
278
Supported values for specific clients:
280
:evolution: Use Evolution.
283
:thunderbird: Use Mozilla Thunderbird or Icedove. For Thunderbird/Icedove 1.5,
284
this works around some bugs that xdg-email doesn't handle.
286
Supported generic values are:
289
:editor: Use your editor to compose the merge request. This also uses
290
your commit id, (see ``bzr whoami``), smtp_server and (optionally)
291
smtp_username and smtp_password.
292
:mapi: Use your preferred e-mail client on Windows.
293
:xdg-email: Use xdg-email to run your preferred mail program
297
The branch you intend to submit your current work to. This is automatically
298
set by ``bzr send``, and is also used by the ``submit:`` revision spec. This
299
should usually be set on a per-branch or per-location basis.
303
A publically-accessible version of this branch (implying that this version is
304
not publically-accessible). Used (and set) by ``bzr send``.
310
These options apply only to branches that use the "dirstate-tags" format. They
311
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
312
manually set in ``locations.conf`` or ``bazaar.conf``.
314
append_revisions_only
315
---------------------
316
If set to "True" then revisions can only be appended to the log, not
317
removed. A branch with this setting enabled can only pull from
318
another branch if the other branch's log is a longer version of its
319
own. This is normally set by ``bzr init --append-revisions-only``.
323
If present, the location of the default branch for pull or merge.
324
This option is normally set by ``pull --remember`` or ``merge
329
If present, the location of the default branch for push. This option
330
is normally set by ``push --remember``.
334
The location that commits should go to when acting as a checkout.
335
This option is normally set by ``bind``.
339
If set to "True", the branch should act as a checkout, and push each commit to
340
the bound_location. This option is normally set by ``bind``/``unbind``.
added
removed
doc/en/user-guide/configuration.txt
