~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Vincent Ladeuil
  • Date: 2012-03-13 17:25:29 UTC
  • mfrom: (6499 +trunk)
  • mto: This revision was merged to the branch mainline in revision 6501.
  • Revision ID: v.ladeuil+lp@free.fr-20120313172529-i0suyjnepsor25i7
Merge trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
14
14
 
15
15
  "John Doe <jdoe@example.com>"
16
16
 
17
 
See also the ``email`` configuration value.
 
17
See also the ``email`` configuration option.
18
18
 
19
19
BZR_PROGRESS_BAR
20
20
~~~~~~~~~~~~~~~~
21
21
 
22
 
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.
23
25
 
24
26
BZR_SIGQUIT_PDB
25
27
~~~~~~~~~~~~~~~
52
54
 
53
55
Path to the Bazaar executable to use when using the bzr+ssh protocol.
54
56
 
55
 
See also the ``bzr_remote_path`` configuration value.
 
57
See also the ``bzr_remote_path`` configuration option.
56
58
 
57
59
BZR_EDITOR
58
60
~~~~~~~~~~
219
221
~~~~~~~~~~~~~~
220
222
 
221
223
An ini file has three types of contructs: section headers, section
222
 
variables and comments.
 
224
options and comments.
223
225
 
224
226
Comments
225
227
^^^^^^^^
238
240
 
239
241
The only valid section headers for bazaar.conf currently are [DEFAULT] and
240
242
[ALIASES].  Section headers are case sensitive. The default section provides for
241
 
setting variables which can be overridden with the branch config file.
 
243
setting options which can be overridden with the branch config file.
242
244
 
243
 
For ``locations.conf``, the variables from the section with the
 
245
For ``locations.conf``, the options from the section with the
244
246
longest matching section header are used to the exclusion of other
245
247
potentially valid section headers. A section header uses the path for
246
248
the branch as the section header. Some examples include::
249
251
    [/home/jdoe/branches/]
250
252
 
251
253
 
252
 
Section variables
253
 
^^^^^^^^^^^^^^^^^
 
254
Section options
 
255
^^^^^^^^^^^^^^^
254
256
 
255
 
A section variable resides within a section. A section variable contains a
256
 
variable name, an equals sign and a value.  For example::
 
257
A section option resides within a section. A section option contains an
 
258
option name, an equals sign and a value.  For example::
257
259
 
258
260
    email            = John Doe <jdoe@isp.com>
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
 
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
268
275
there are three policies available:
269
276
 
270
277
 none:
277
284
   for contained locations, any additional path components are
278
285
   appended to the value.
279
286
 
280
 
Policies are specified by keys with names of the form "$var:policy".
 
287
Policies are specified by keys with names of the form "<option_name>:policy".
281
288
For example, to define the push location for a tree of branches, the
282
289
following could be used::
283
290
 
288
295
With this configuration, the push location for ``/top/location/branch1``
289
296
would be ``sftp://example.com/location/branch1``.
290
297
 
 
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
When an option is local to a Section, it cannot be referred to from option
 
337
values in any other section from the same ``Store`` nor from any other
 
338
``Store``.
 
339
 
291
340
 
292
341
The main configuration file, bazaar.conf
293
342
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302
351
    [DEFAULT]
303
352
    email             = John Doe <jdoe@isp.com>
304
353
    editor            = /usr/bin/vim
305
 
    check_signatures  = check-available
306
354
    create_signatures = when-required
307
355
 
308
356
 
320
368
 
321
369
    [http://hypothetical.site.com/branches/devel-branch]
322
370
    create_signatures = always
323
 
    check_signatures  = always
324
 
 
325
 
    [http://bazaar-vcs.org/bzr/*]
326
 
    check_signatures  = require
327
371
 
328
372
The authentication configuration file, authentication.conf
329
373
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
333
377
of bzr that requires authentication (smtp for example).
334
378
 
335
379
The syntax of the file obeys the same rules as the others except for the
336
 
variable policies which don't apply.
 
380
option policies which don't apply.
337
381
 
338
382
For more information on the possible uses of the authentication configuration
339
383
file see :doc:`authentication-help`.
340
384
 
341
385
 
342
 
Common variable options
343
 
-----------------------
 
386
Common options
 
387
--------------
344
388
 
345
389
debug_flags
346
390
~~~~~~~~~~~
351
395
 
352
396
    debug_flags = hpss
353
397
 
 
398
or::
 
399
 
 
400
    debug_flags = hpss,evil
 
401
 
354
402
email
355
403
~~~~~
356
404
 
377
425
check_signatures
378
426
~~~~~~~~~~~~~~~~
379
427
 
380
 
Defines the behavior for signatures.
 
428
Reserved for future use.  These options will allow a policy for branches to
 
429
require signatures.
381
430
 
382
431
require
383
432
    The gnupg signature for revisions must be present and must be valid.
393
442
create_signatures
394
443
~~~~~~~~~~~~~~~~~
395
444
 
396
 
Defines the behaviour of signing revisions.
 
445
Defines the behaviour of signing revisions on commits.  By default bzr will not
 
446
sign new commits.
397
447
 
398
448
always
399
 
    Sign every new revision that is committed.
 
449
    Sign every new revision that is committed.  If the signing fails then the
 
450
    commit will not be made.
400
451
 
401
452
when-required
402
 
    (default) Sign newly committed revisions only when the branch requires
403
 
    signed revisions.
 
453
    Reserved for future use.
404
454
 
405
455
never
406
 
    Refuse to sign newly committed revisions, even if the branch
407
 
    requires signatures.
 
456
    Reserved for future use.
 
457
 
 
458
In future it is planned that ``when-required`` will sign newly
 
459
committed revisions only when the branch requires them.  ``never`` will refuse
 
460
to sign newly committed revisions, even if the branch requires signatures.
 
461
 
 
462
dirstate.fdatasync
 
463
~~~~~~~~~~~~~~~~~~
 
464
 
 
465
If true (default), working tree metadata changes are flushed through the
 
466
OS buffers to physical disk.  This is somewhat slower, but means data
 
467
should not be lost if the machine crashes.  See also repository.fdatasync.
 
468
 
 
469
gpg_signing_key
 
470
~~~~~~~~~~~~~~~
 
471
 
 
472
The GnuPG user identity to use when signing commits.  Can be an e-mail
 
473
address, key fingerprint or full key ID.  When unset or when set to
 
474
"default" Bazaar will use the user e-mail set with ``whoami``.
408
475
 
409
476
recurse
410
477
~~~~~~~
427
494
 
428
495
    gpg_signing_command = /usr/bin/gnpg
429
496
 
 
497
The specified command must accept the options "--clearsign" and "-u <email>".
 
498
 
430
499
bzr_remote_path
431
500
~~~~~~~~~~~~~~~
432
501
 
453
522
These settings are only needed if the SMTP server requires authentication
454
523
to send mail.
455
524
 
 
525
locks.steal_dead
 
526
~~~~~~~~~~~~~~~~
 
527
 
 
528
If set to true, bzr will automatically break locks held by processes from
 
529
the same machine and user that are no longer alive.  Otherwise, it will
 
530
print a message and you can break the lock manually, if you are satisfied
 
531
the object is no longer in use.
 
532
 
456
533
mail_client
457
534
~~~~~~~~~~~
458
535
 
479
556
:mapi: Use your preferred e-mail client on Windows.
480
557
:xdg-email: Use xdg-email to run your preferred mail program
481
558
 
 
559
repository.fdatasync
 
560
~~~~~~~~~~~~~~~~~~~~
 
561
 
 
562
If true (default), repository changes are flushed through the OS buffers
 
563
to physical disk.  This is somewhat slower, but means data should not be
 
564
lost if the machine crashes.  See also dirstate.fdatasync.
 
565
 
482
566
submit_branch
483
567
~~~~~~~~~~~~~
484
568
 
504
588
    whether the format deprecation warning is shown on repositories that are
505
589
    using deprecated formats.
506
590
 
 
591
default_format
 
592
~~~~~~~~~~~~~~
 
593
 
 
594
A format name for the default format used when creating branches.  See ``bzr
 
595
help formats`` for possible values.
 
596
 
507
597
 
508
598
Unicode options
509
599
---------------
537
627
parent_location
538
628
~~~~~~~~~~~~~~~
539
629
 
540
 
If present, the location of the default branch for pull or merge.
541
 
This option is normally set by ``pull --remember`` or ``merge
 
630
If present, the location of the default branch for pull or merge.  This option
 
631
is normally set when creating a branch, the first ``pull`` or by ``pull
542
632
--remember``.
543
633
 
544
634
push_location
545
635
~~~~~~~~~~~~~
546
636
 
547
637
If present, the location of the default branch for push.  This option
548
 
is normally set by ``push --remember``.
 
638
is normally set by the first ``push`` or ``push --remember``.
549
639
 
550
640
push_strict
551
641
~~~~~~~~~~~
578
668
If present, defines the ``--strict`` option default value for checking
579
669
uncommitted changes before sending a merge directive.
580
670
 
 
671
add.maximum_file_size
 
672
~~~~~~~~~~~~~~~~~~~~~
 
673
 
 
674
Defines the maximum file size the command line "add" operation will allow
 
675
in recursive mode, with files larger than this value being skipped. You may 
 
676
specify this value as an integer (in which case it is interpreted as bytes), 
 
677
or you may specify the value using SI units, i.e. 10KB, 20MB, 1G. A value of 0 
 
678
will disable skipping.
 
679
 
 
680
External Merge Tools
 
681
--------------------
 
682
 
 
683
bzr.mergetool.<name>
 
684
~~~~~~~~~~~~~~~~~~~~
 
685
 
 
686
Defines an external merge tool called <name> with the given command-line.
 
687
Arguments containing spaces should be quoted using single or double quotes. The
 
688
executable may omit its path if it can be found on the PATH.
 
689
 
 
690
The following markers can be used in the command-line to substitute filenames
 
691
involved in the merge conflict::
 
692
 
 
693
  {base}      file.BASE
 
694
  {this}      file.THIS
 
695
  {other}     file.OTHER
 
696
  {result}    output file
 
697
  {this_temp} temp copy of file.THIS, used to overwrite output file if merge
 
698
              succeeds.
 
699
 
 
700
For example::
 
701
 
 
702
  bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
703
 
 
704
bzr.default_mergetool
 
705
~~~~~~~~~~~~~~~~~~~~~
 
706
 
 
707
Specifies which external merge tool (as defined above) should be selected by
 
708
default in tools such as ``bzr qconflicts``.
 
709
 
 
710
For example::
 
711
 
 
712
  bzr.default_mergetool = kdiff3