~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: 2009-06-30 17:12:32 UTC
  • mfrom: (4398.3.2 register-serializer9)
  • Revision ID: pqm@pqm.ubuntu.com-20090630171232-h997nd3w5w89v60t
(Jelmer) Pass create_prefix paremeter to BzrDir.push_branch.

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_PLUGIN_PATH
 
63
~~~~~~~~~~~~~~~
 
64
 
 
65
The path to the plugins directory that Bazaar should use.
 
66
 
 
67
BZRPATH
 
68
~~~~~~~
 
69
 
 
70
The path where Bazaar should look for shell plugin external commands.
 
71
 
 
72
 
 
73
Configuration files
 
74
-------------------
 
75
 
 
76
Location
 
77
~~~~~~~~
 
78
 
 
79
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
 
80
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
 
81
Windows. (You can check the location for your system by using
 
82
``bzr version``.)
 
83
 
 
84
There are three primary configuration files in this location:
 
85
 
 
86
* ``bazaar.conf`` describes default configuration options,
 
87
 
 
88
* ``locations.conf`` describes configuration information for
 
89
  specific branch locations,
 
90
 
 
91
* ``authentication.conf`` describes credential information for
 
92
  remote servers.
 
93
 
 
94
Each branch can also contain a configuration file that sets values specific
 
95
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
 
96
branch. This file is visible to all users of a branch, if you wish to override
 
97
one of the values for a branch with a setting that is specific to you then you
 
98
can do so in ``locations.conf``.
 
99
 
 
100
General format
 
101
~~~~~~~~~~~~~~
 
102
 
 
103
An ini file has three types of contructs: section headers, section
 
104
variables and comments.
 
105
 
 
106
Comments
 
107
^^^^^^^^
 
108
 
 
109
A comment is any line that starts with a "#" (sometimes called a "hash
 
110
mark", "pound sign" or "number sign"). Comment lines are ignored by
 
111
Bazaar when parsing ini files.
 
112
 
 
113
Section headers
 
114
^^^^^^^^^^^^^^^
 
115
 
 
116
A section header is a word enclosed in brackets that starts at the begining
 
117
of a line.  A typical section header looks like this::
 
118
 
 
119
    [DEFAULT]
 
120
 
 
121
The only valid section headers for bazaar.conf currently are [DEFAULT] and
 
122
[ALIASES].  Section headers are case sensitive. The default section provides for
 
123
setting variables which can be overridden with the branch config file.
 
124
 
 
125
For ``locations.conf``, the variables from the section with the
 
126
longest matching section header are used to the exclusion of other
 
127
potentially valid section headers. A section header uses the path for
 
128
the branch as the section header. Some examples include::
 
129
 
 
130
    [http://mybranches.isp.com/~jdoe/branchdir]
 
131
    [/home/jdoe/branches/]
 
132
 
 
133
 
 
134
Section variables
 
135
^^^^^^^^^^^^^^^^^
 
136
 
 
137
A section variable resides within a section. A section variable contains a
 
138
variable name, an equals sign and a value.  For example::
 
139
 
 
140
    email            = John Doe <jdoe@isp.com>
 
141
    check_signatures = require
 
142
 
 
143
 
 
144
Variable policies
 
145
^^^^^^^^^^^^^^^^^
 
146
 
 
147
Variables defined in a section affect the named directory or URL plus
 
148
any locations they contain.  Policies can be used to change how a
 
149
variable value is interpreted for contained locations.  Currently
 
150
there are three policies available:
 
151
 
 
152
 none:
 
153
   the value is interpreted the same for contained locations.  This is
 
154
   the default behaviour.
 
155
 norecurse:
 
156
   the value is only used for the exact location specified by the
 
157
   section name.
 
158
 appendpath:
 
159
   for contained locations, any additional path components are
 
160
   appended to the value.
 
161
 
 
162
Policies are specified by keys with names of the form "$var:policy".
 
163
For example, to define the push location for a tree of branches, the
 
164
following could be used::
 
165
 
 
166
  [/top/location]
 
167
  push_location = sftp://example.com/location
 
168
  push_location:policy = appendpath
 
169
 
 
170
With this configuration, the push location for ``/top/location/branch1``
 
171
would be ``sftp://example.com/location/branch1``.
 
172
 
 
173
 
 
174
The main configuration file, bazaar.conf
 
175
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
176
 
 
177
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
 
178
The default section contains the default
 
179
configuration options for all branches. The default section can be
 
180
overriden by providing a branch-specific section in ``locations.conf``.
 
181
 
 
182
A typical ``bazaar.conf`` section often looks like the following::
 
183
 
 
184
    [DEFAULT]
 
185
    email             = John Doe <jdoe@isp.com>
 
186
    editor            = /usr/bin/vim
 
187
    check_signatures  = check-available
 
188
    create_signatures = when-required
 
189
 
 
190
 
 
191
The branch location configuration file, locations.conf
 
192
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
193
 
 
194
``locations.conf`` allows one to specify overriding settings for
 
195
a specific branch. The format is almost identical to the default section in
 
196
bazaar.conf with one significant change: The section header, instead of saying
 
197
default, will be the path to a branch that you wish to override a value
 
198
for. The '?' and '*' wildcards are supported::
 
199
 
 
200
    [/home/jdoe/branches/nethack]
 
201
    email = Nethack Admin <nethack@nethack.com>
 
202
 
 
203
    [http://hypothetical.site.com/branches/devel-branch]
 
204
    create_signatures = always
 
205
    check_signatures  = always
 
206
 
 
207
    [http://bazaar-vcs.org/bzr/*]
 
208
    check_signatures  = require
 
209
 
 
210
The authentication configuration file, authentication.conf
 
211
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
212
 
 
213
``authentication.conf`` allows one to specify credentials for
 
214
remote servers. This can be used for all the supported transports and any part
 
215
of bzr that requires authentication (smtp for example).
 
216
 
 
217
The syntax of the file obeys the same rules as the others except for the
 
218
variable policies which don't apply.
 
219
 
 
220
For more information on the possible uses of the authentication configuration
 
221
file see `Authentication Settings`_.
 
222
 
 
223
 
 
224
Common variable options
 
225
-----------------------
 
226
 
 
227
debug_flags
 
228
~~~~~~~~~~~
 
229
 
 
230
A comma-separated list of debugging options to turn on.  The same values
 
231
can be used as with the -D command-line option (see `help global-options`).
 
232
For example::
 
233
 
 
234
    debug_flags = hpss
 
235
 
 
236
email
 
237
~~~~~
 
238
 
 
239
The email address to use when committing a branch. Typically takes the form
 
240
of::
 
241
 
 
242
    email = Full Name <account@hostname.tld>
 
243
 
 
244
editor
 
245
~~~~~~
 
246
 
 
247
The path of the editor that you wish to use if *bzr commit* is run without
 
248
a commit message. This setting is trumped by the environment variable
 
249
``BZR_EDITOR``, and overrides the ``VISUAL`` and ``EDITOR`` environment
 
250
variables.
 
251
 
 
252
log_format
 
253
~~~~~~~~~~
 
254
 
 
255
The default log format to use. Standard log formats are ``long``, ``short``
 
256
and ``line``. Additional formats may be provided by plugins. The default
 
257
value is ``long``.
 
258
 
 
259
check_signatures
 
260
~~~~~~~~~~~~~~~~
 
261
 
 
262
Defines the behavior for signatures.
 
263
 
 
264
require
 
265
    The gnupg signature for revisions must be present and must be valid.
 
266
 
 
267
ignore
 
268
    Do not check gnupg signatures of revisions.
 
269
 
 
270
check-available
 
271
    (default) If gnupg signatures for revisions are present, check them.
 
272
    Bazaar will fail if it finds a bad signature, but will not fail if
 
273
    no signature is present.
 
274
 
 
275
create_signatures
 
276
~~~~~~~~~~~~~~~~~
 
277
 
 
278
Defines the behaviour of signing revisions.
 
279
 
 
280
always
 
281
    Sign every new revision that is committed.
 
282
 
 
283
when-required
 
284
    (default) Sign newly committed revisions only when the branch requires
 
285
    signed revisions.
 
286
 
 
287
never
 
288
    Refuse to sign newly committed revisions, even if the branch
 
289
    requires signatures.
 
290
 
 
291
recurse
 
292
~~~~~~~
 
293
 
 
294
Only useful in ``locations.conf``. Defines whether or not the
 
295
configuration for this section applies to subdirectories:
 
296
 
 
297
true
 
298
    (default) This section applies to subdirectories as well.
 
299
 
 
300
false
 
301
    This section only applies to the branch at this directory and not
 
302
    branches below it.
 
303
 
 
304
gpg_signing_command
 
305
~~~~~~~~~~~~~~~~~~~
 
306
 
 
307
(Default: "gpg"). Which program should be used to sign and check revisions.
 
308
For example::
 
309
 
 
310
    gpg_signing_command = /usr/bin/gnpg
 
311
 
 
312
bzr_remote_path
 
313
~~~~~~~~~~~~~~~
 
314
 
 
315
(Default: "bzr").  The path to the command that should be used to run the smart
 
316
server for bzr.  This value may only be specified in locations.conf, because:
 
317
 
 
318
- it's needed before branch.conf is accessible
 
319
- allowing remote branch.conf files to specify commands would be a security
 
320
  risk
 
321
 
 
322
It is overridden by the BZR_REMOTE_PATH environment variable.
 
323
 
 
324
smtp_server
 
325
~~~~~~~~~~~
 
326
 
 
327
(Default: "localhost"). SMTP server to use when Bazaar needs to send
 
328
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
 
329
 
 
330
smtp_username, smtp_password
 
331
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
332
 
 
333
User and password to authenticate to the SMTP server. If smtp_username
 
334
is set, and smtp_password is not, Bazaar will prompt for a password.
 
335
These settings are only needed if the SMTP server requires authentication
 
336
to send mail.
 
337
 
 
338
mail_client
 
339
~~~~~~~~~~~
 
340
 
 
341
A mail client to use for sending merge requests.
 
342
By default, bzr will try to use ``mapi`` on Windows.  On other platforms, it
 
343
will try ``xdg-email``. If either of these fails, it will fall back to
 
344
``editor``.
 
345
 
 
346
Supported values for specific clients:
 
347
 
 
348
:claws: Use Claws.  This skips a dialog for attaching files.
 
349
:evolution: Use Evolution.
 
350
:kmail: Use KMail.
 
351
:mutt: Use Mutt.
 
352
:thunderbird: Use Mozilla Thunderbird or Icedove.  For Thunderbird/Icedove 1.5,
 
353
    this works around some bugs that xdg-email doesn't handle.
 
354
 
 
355
Supported generic values are:
 
356
 
 
357
:default: See above.
 
358
:editor: Use your editor to compose the merge request.  This also uses
 
359
    your commit id, (see ``bzr whoami``), smtp_server and (optionally)
 
360
    smtp_username and smtp_password.
 
361
:mapi: Use your preferred e-mail client on Windows.
 
362
:xdg-email: Use xdg-email to run your preferred mail program
 
363
 
 
364
submit_branch
 
365
~~~~~~~~~~~~~
 
366
 
 
367
The branch you intend to submit your current work to.  This is automatically
 
368
set by ``bzr send``, and is also used by the ``submit:`` revision spec.  This
 
369
should usually be set on a per-branch or per-location basis.
 
370
 
 
371
public_branch
 
372
~~~~~~~~~~~~~
 
373
 
 
374
A publically-accessible version of this branch (implying that this version is
 
375
not publically-accessible).  Used (and set) by ``bzr send``.
 
376
 
 
377
 
 
378
Branch type specific options
 
379
----------------------------
 
380
 
 
381
These options apply only to branches that use the ``dirstate-tags`` or
 
382
later format.  They
 
383
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
 
384
manually set in ``locations.conf`` or ``bazaar.conf``.
 
385
 
 
386
append_revisions_only
 
387
~~~~~~~~~~~~~~~~~~~~~
 
388
 
 
389
If set to "True" then revisions can only be appended to the log, not
 
390
removed.  A branch with this setting enabled can only pull from
 
391
another branch if the other branch's log is a longer version of its
 
392
own.  This is normally set by ``bzr init --append-revisions-only``.
 
393
 
 
394
parent_location
 
395
~~~~~~~~~~~~~~~
 
396
 
 
397
If present, the location of the default branch for pull or merge.
 
398
This option is normally set by ``pull --remember`` or ``merge
 
399
--remember``.
 
400
 
 
401
push_location
 
402
~~~~~~~~~~~~~
 
403
 
 
404
If present, the location of the default branch for push.  This option
 
405
is normally set by ``push --remember``.
 
406
 
 
407
push_strict
 
408
~~~~~~~~~~~
 
409
 
 
410
If present, defines the ``--strict`` option default value for checking
 
411
uncommitted changes before pushing.
 
412
 
 
413
bound_location
 
414
~~~~~~~~~~~~~~
 
415
 
 
416
The location that commits should go to when acting as a checkout.
 
417
This option is normally set by ``bind``.
 
418
 
 
419
bound
 
420
~~~~~
 
421
 
 
422
If set to "True", the branch should act as a checkout, and push each commit to
 
423
the bound_location.  This option is normally set by ``bind``/``unbind``.