/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/help_topics/en/configuration.txt

  • Committer: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
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.
9
9
 
10
 
BRZ_EMAIL
 
10
BZR_EMAIL
11
11
~~~~~~~~~
12
12
 
13
 
Override the email id used by Breezy.  Typical format::
 
13
Override the email id used by Bazaar.  Typical format::
14
14
 
15
15
  "John Doe <jdoe@example.com>"
16
16
 
17
 
See also the ``email`` configuration option.
 
17
See also the ``email`` configuration value.
18
18
 
19
 
BRZ_PROGRESS_BAR
 
19
BZR_PROGRESS_BAR
20
20
~~~~~~~~~~~~~~~~
21
21
 
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"
25
23
 
26
 
BRZ_SIGQUIT_PDB
 
24
BZR_SIGQUIT_PDB
27
25
~~~~~~~~~~~~~~~
28
26
 
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)
33
31
 
34
 
BRZ_HOME
 
32
BZR_HOME
35
33
~~~~~~~~
36
34
 
37
 
Override the home directory used by Breezy.
 
35
Override the home directory used by Bazaar.
38
36
 
39
 
BRZ_SSH
 
37
BZR_SSH
40
38
~~~~~~~
41
39
 
42
40
Select a different SSH implementation.
43
41
 
44
 
BRZ_PDB
 
42
BZR_PDB
45
43
~~~~~~~
46
44
 
47
45
Control whether to launch a debugger on error.
52
50
BZR_REMOTE_PATH
53
51
~~~~~~~~~~~~~~~
54
52
 
55
 
Path to the Bazaar or Breezy executable to use when using the bzr+ssh protocol.
56
 
 
57
 
See also the ``bzr_remote_path`` configuration option.
58
 
 
59
 
BRZ_EDITOR
 
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
60
58
~~~~~~~~~~
61
59
 
62
 
Path to the editor Breezy should use for commit messages, etc.
 
60
Path to the editor Bazaar should use for commit messages, etc.
63
61
 
64
 
BRZ_LOG
 
62
BZR_LOG
65
63
~~~~~~~
66
64
 
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``.
69
67
 
70
68
The log file contains debug information that is useful for diagnosing or
71
 
reporting problems with Breezy.
 
69
reporting problems with Bazaar.
72
70
 
73
71
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
74
72
will disable logging.
75
73
 
76
74
 
77
 
BRZ_PLUGIN_PATH
 
75
BZR_PLUGIN_PATH
78
76
~~~~~~~~~~~~~~~
79
77
 
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:
82
80
 
83
81
* the user specific plugin directory (containing the ``user`` plugins),
84
82
 
85
 
* the breezy directory (containing the ``core`` plugins),
 
83
* the bzrlib directory (containing the ``core`` plugins),
86
84
 
87
85
* the site specific plugin directory if applicable (containing
88
86
  the ``site`` plugins).
132
130
 
133
131
  BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user
134
132
 
135
 
BRZ_DISABLE_PLUGINS
 
133
BZR_DISABLE_PLUGINS
136
134
~~~~~~~~~~~~~~~~~~~
137
135
 
138
136
Under special circumstances (mostly when trying to diagnose a
148
146
 
149
147
  BZR_DISABLE_PLUGINS='myplugin:yourplugin'
150
148
 
151
 
BRZ_PLUGINS_AT
 
149
BZR_PLUGINS_AT
152
150
~~~~~~~~~~~~~~
153
151
 
154
152
When adding a new feature or working on a bug in a plugin,
175
173
Using a specific version of ``myplugin``:
176
174
``BZR_PLUGINS_AT='myplugin@/home/me/bugfixes/123456-myplugin``
177
175
 
178
 
BRZPATH
 
176
BZRPATH
179
177
~~~~~~~
180
178
 
181
 
The path where Breezy should look for shell plugin external commands.
 
179
The path where Bazaar should look for shell plugin external commands.
182
180
 
183
181
 
184
182
http_proxy, https_proxy
197
195
~~~~~~~~
198
196
 
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``.)
203
201
 
204
202
There are three primary configuration files in this location:
205
203
 
206
 
* ``breezy.conf`` describes default configuration options,
 
204
* ``bazaar.conf`` describes default configuration options,
207
205
 
208
206
* ``locations.conf`` describes configuration information for
209
207
  specific branch locations,
221
219
~~~~~~~~~~~~~~
222
220
 
223
221
An ini file has three types of contructs: section headers, section
224
 
options and comments.
 
222
variables and comments.
225
223
 
226
224
Comments
227
225
^^^^^^^^
228
226
 
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.
232
230
 
233
231
Section headers
234
232
^^^^^^^^^^^^^^^
238
236
 
239
237
    [DEFAULT]
240
238
 
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.
244
242
 
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/]
252
250
 
253
251
 
254
 
Section options
255
 
^^^^^^^^^^^^^^^
 
252
Section variables
 
253
^^^^^^^^^^^^^^^^^
256
254
 
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::
259
257
 
260
258
    email            = John Doe <jdoe@isp.com>
261
 
    gpg_signing_key  = Amy Pond <amy@example.com>
262
 
 
263
 
A option can reference other options by enclosing them in curly brackets::
264
 
 
265
 
    my_branch_name = feature_x
266
 
    my_server      = bzr+ssh://example.com
267
 
    push_location   = {my_server}/project/{my_branch_name}
268
 
 
269
 
Option policies
270
 
^^^^^^^^^^^^^^^
271
 
 
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
 
260
 
 
261
 
 
262
Variable policies
 
263
^^^^^^^^^^^^^^^^^
 
264
 
 
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:
276
269
 
277
270
 none:
284
277
   for contained locations, any additional path components are
285
278
   appended to the value.
286
279
 
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::
290
283
 
295
288
With this configuration, the push location for ``/top/location/branch1``
296
289
would be ``sftp://example.com/location/branch1``.
297
290
 
298
 
Section local options
299
 
^^^^^^^^^^^^^^^^^^^^^
300
 
 
301
 
Some options are defined automatically inside a given section and can be
302
 
refered to in this section only. 
303
 
 
304
 
For example, the ``appendpath`` policy can be used like this::
305
 
 
306
 
  [/home/vila/src/bzr/bugs]
307
 
  mypush = lp:~vila/bzr
308
 
  mypush:policy=appendpath
309
 
 
310
 
Using ``relpath`` to achieve the same result is done like this::
311
 
 
312
 
  [/home/vila/src/bzr/bugs]
313
 
  mypush = lp:~vila/bzr/{relpath}
314
 
 
315
 
In both cases, when used in a directory like
316
 
``/home/vila/src/bzr/bugs/832013-expand-in-stack`` we'll get::
317
 
 
318
 
   $ bzr config mypush
319
 
   lp:~vila/bzr/832013-expand-in-stack
320
 
 
321
 
Another such option is ``basename`` which can be used like this::
322
 
 
323
 
  [/home/vila/src/bzr]
324
 
  mypush = lp:~vila/bzr/{basename}
325
 
 
326
 
When used in a directory like
327
 
``/home/vila/src/bzr/bugs/832013-expand-in-stack`` we'll get::
328
 
 
329
 
   $ bzr config mypush
330
 
   lp:~vila/bzr/832013-expand-in-stack
331
 
 
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
334
 
location it matches.
335
 
 
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
338
 
like this::
339
 
 
340
 
  [/home/vila/src/bzr/bugs]
341
 
  mypush = lp:~vila/bzr/{branchname}
342
 
 
343
 
When used with a colocated branch named ``832013-expand-in-stack``, we'll get::
344
 
 
345
 
  bzr config mypush
346
 
  lp:~vila/bzr/832013-expand-in-stack
347
 
 
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
350
 
``Store``.
351
 
 
352
 
 
353
 
The main configuration file, breezy.conf
 
291
 
 
292
The main configuration file, bazaar.conf
354
293
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355
294
 
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``.
360
299
 
361
 
A typical ``breezy.conf`` section often looks like the following::
 
300
A typical ``bazaar.conf`` section often looks like the following::
362
301
 
363
302
    [DEFAULT]
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
367
307
 
368
308
 
371
311
 
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::
377
317
 
380
320
 
381
321
    [http://hypothetical.site.com/branches/devel-branch]
382
322
    create_signatures = always
 
323
    check_signatures  = always
 
324
 
 
325
    [http://bazaar-vcs.org/bzr/*]
 
326
    check_signatures  = require
383
327
 
384
328
The authentication configuration file, authentication.conf
385
329
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
389
333
of bzr that requires authentication (smtp for example).
390
334
 
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.
393
337
 
394
338
For more information on the possible uses of the authentication configuration
395
339
file see :doc:`authentication-help`.
396
340
 
397
341
 
398
 
Common options
399
 
--------------
 
342
Common variable options
 
343
-----------------------
400
344
 
401
345
debug_flags
402
346
~~~~~~~~~~~
407
351
 
408
352
    debug_flags = hpss
409
353
 
410
 
or::
411
 
 
412
 
    debug_flags = hpss,evil
413
 
 
414
354
email
415
355
~~~~~
416
356
 
437
377
check_signatures
438
378
~~~~~~~~~~~~~~~~
439
379
 
440
 
Reserved for future use.  These options will allow a policy for branches to
441
 
require signatures.
 
380
Defines the behavior for signatures.
442
381
 
443
382
require
444
383
    The gnupg signature for revisions must be present and must be valid.
448
387
 
449
388
check-available
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.
453
392
 
454
393
create_signatures
455
394
~~~~~~~~~~~~~~~~~
456
395
 
457
 
Defines the behaviour of signing revisions on commits.  By default bzr will not
458
 
sign new commits.
 
396
Defines the behaviour of signing revisions.
459
397
 
460
398
always
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.
463
400
 
464
401
when-required
465
 
    Reserved for future use.
 
402
    (default) Sign newly committed revisions only when the branch requires
 
403
    signed revisions.
466
404
 
467
405
never
468
 
    Reserved for future use.
469
 
 
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.
473
 
 
474
 
dirstate.fdatasync
475
 
~~~~~~~~~~~~~~~~~~
476
 
 
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.
480
 
 
481
 
gpg_signing_key
482
 
~~~~~~~~~~~~~~~
483
 
 
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
 
407
    requires signatures.
487
408
 
488
409
recurse
489
410
~~~~~~~
498
419
    This section only applies to the branch at this directory and not
499
420
    branches below it.
500
421
 
 
422
gpg_signing_command
 
423
~~~~~~~~~~~~~~~~~~~
 
424
 
 
425
(Default: "gpg"). Which program should be used to sign and check revisions.
 
426
For example::
 
427
 
 
428
    gpg_signing_command = /usr/bin/gnpg
 
429
 
501
430
bzr_remote_path
502
431
~~~~~~~~~~~~~~~
503
432
 
513
442
smtp_server
514
443
~~~~~~~~~~~
515
444
 
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.
518
447
 
519
448
smtp_username, smtp_password
520
449
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
521
450
 
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
525
454
to send mail.
526
455
 
527
 
locks.steal_dead
528
 
~~~~~~~~~~~~~~~~
529
 
 
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.
534
 
 
535
456
mail_client
536
457
~~~~~~~~~~~
537
458
 
558
479
:mapi: Use your preferred e-mail client on Windows.
559
480
:xdg-email: Use xdg-email to run your preferred mail program
560
481
 
561
 
repository.fdatasync
562
 
~~~~~~~~~~~~~~~~~~~~
563
 
 
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.
567
 
 
568
482
submit_branch
569
483
~~~~~~~~~~~~~
570
484
 
590
504
    whether the format deprecation warning is shown on repositories that are
591
505
    using deprecated formats.
592
506
 
593
 
* ``insecure_permissions``:
594
 
    whether a warning is shown if ``authentication.conf`` can be read
595
 
    by other users.
596
 
 
597
 
default_format
598
 
~~~~~~~~~~~~~~
599
 
 
600
 
A format name for the default format used when creating branches.  See ``bzr
601
 
help formats`` for possible values.
602
 
 
603
507
 
604
508
Unicode options
605
509
---------------
618
522
These options apply only to branches that use the ``dirstate-tags`` or
619
523
later format.  They
620
524
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
621
 
manually set in ``locations.conf`` or ``breezy.conf``.
 
525
manually set in ``locations.conf`` or ``bazaar.conf``.
622
526
 
623
527
append_revisions_only
624
528
~~~~~~~~~~~~~~~~~~~~~
633
537
parent_location
634
538
~~~~~~~~~~~~~~~
635
539
 
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
638
542
--remember``.
639
543
 
640
544
push_location
641
545
~~~~~~~~~~~~~
642
546
 
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``.
645
549
 
646
550
push_strict
647
551
~~~~~~~~~~~
649
553
If present, defines the ``--strict`` option default value for checking
650
554
uncommitted changes before pushing.
651
555
 
 
556
dpush_strict
 
557
~~~~~~~~~~~~
 
558
 
 
559
If present, defines the ``--strict`` option default value for checking
 
560
uncommitted changes before pushing into a different VCS without any
 
561
custom bzr metadata.
 
562
 
652
563
bound_location
653
564
~~~~~~~~~~~~~~
654
565
 
667
578
If present, defines the ``--strict`` option default value for checking
668
579
uncommitted changes before sending a merge directive.
669
580
 
670
 
add.maximum_file_size
671
 
~~~~~~~~~~~~~~~~~~~~~
672
 
 
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.
678
 
 
679
 
External Merge Tools
680
 
--------------------
681
 
 
682
 
bzr.mergetool.<name>
683
 
~~~~~~~~~~~~~~~~~~~~
684
 
 
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.
688
 
 
689
 
The following markers can be used in the command-line to substitute filenames
690
 
involved in the merge conflict::
691
 
 
692
 
  {base}      file.BASE
693
 
  {this}      file.THIS
694
 
  {other}     file.OTHER
695
 
  {result}    output file
696
 
  {this_temp} temp copy of file.THIS, used to overwrite output file if merge
697
 
              succeeds.
698
 
 
699
 
For example::
700
 
 
701
 
  bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
702
 
 
703
 
Because ``mergetool`` and ``config`` itself both use curly braces as
704
 
interpolation markers, trying to display the mergetool line results in the
705
 
following problem::
706
 
 
707
 
 
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}".
711
 
 
712
 
To avoid this, ``config`` can be instructed not to try expanding variables::
713
 
 
714
 
  $ bzr config --all bzr.mergetool.kdiff3
715
 
  branch:
716
 
    bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
717
 
 
718
 
 
719
 
bzr.default_mergetool
720
 
~~~~~~~~~~~~~~~~~~~~~
721
 
 
722
 
Specifies which external merge tool (as defined above) should be selected by
723
 
default in tools such as ``bzr qconflicts``.
724
 
 
725
 
For example::
726
 
 
727
 
  bzr.default_mergetool = kdiff3