/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 breezy/help_topics/en/configuration.txt

  • Committer: Jelmer Vernooij
  • Date: 2020-04-05 19:11:34 UTC
  • mto: (7490.7.16 work)
  • mto: This revision was merged to the branch mainline in revision 7501.
  • Revision ID: jelmer@jelmer.uk-20200405191134-0aebh8ikiwygxma5
Populate the .gitignore file.

Show diffs side-by-side

added added

removed removed

Lines of Context:
breezy/help_topics/en/configuration.txt
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
 
BZR_EMAIL
 
10
BRZ_EMAIL
11
11
~~~~~~~~~
12
12
 
13
 
Override the email id used by Bazaar.  Typical format::
 
13
Override the email id used by Breezy.  Typical format::
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
 
BZR_PROGRESS_BAR
 
19
BRZ_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
 
BZR_SIGQUIT_PDB
 
26
BRZ_SIGQUIT_PDB
25
27
~~~~~~~~~~~~~~~
26
28
 
27
29
Control whether SIGQUIT behaves normally or invokes a breakin debugger.
29
31
* 0 = Standard SIGQUIT behavior (normally, exit with a core dump)
30
32
* 1 = Invoke breakin debugger (default)
31
33
 
32
 
BZR_HOME
 
34
BRZ_HOME
33
35
~~~~~~~~
34
36
 
35
 
Override the home directory used by Bazaar.
 
37
Override the home directory used by Breezy.
36
38
 
37
 
BZR_SSH
 
39
BRZ_SSH
38
40
~~~~~~~
39
41
 
40
42
Select a different SSH implementation.
41
43
 
42
 
BZR_PDB
 
44
BRZ_PDB
43
45
~~~~~~~
44
46
 
45
47
Control whether to launch a debugger on error.
50
52
BZR_REMOTE_PATH
51
53
~~~~~~~~~~~~~~~
52
54
 
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
 
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
58
60
~~~~~~~~~~
59
61
 
60
 
Path to the editor Bazaar should use for commit messages, etc.
 
62
Path to the editor Breezy should use for commit messages, etc.
61
63
 
62
 
BZR_LOG
 
64
BRZ_LOG
63
65
~~~~~~~
64
66
 
65
 
Location of the Bazaar log file. You can check the current location by
 
67
Location of the Breezy log file. You can check the current location by
66
68
running ``bzr version``.
67
69
 
68
70
The log file contains debug information that is useful for diagnosing or
69
 
reporting problems with Bazaar.
 
71
reporting problems with Breezy.
70
72
 
71
73
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
72
74
will disable logging.
73
75
 
74
76
 
75
 
BZR_PLUGIN_PATH
 
77
BRZ_PLUGIN_PATH
76
78
~~~~~~~~~~~~~~~
77
79
 
78
 
The path to the plugins directory that Bazaar should use.
79
 
If not set, Bazaar will search for plugins in:
 
80
The path to the plugins directory that Breezy should use.
 
81
If not set, Breezy will search for plugins in:
80
82
 
81
83
* the user specific plugin directory (containing the ``user`` plugins),
82
84
 
83
 
* the bzrlib directory (containing the ``core`` plugins),
 
85
* the breezy directory (containing the ``core`` plugins),
84
86
 
85
87
* the site specific plugin directory if applicable (containing
86
88
  the ``site`` plugins).
90
92
 
91
93
As for the ``PATH`` variables, if multiple directories are
92
94
specified in ``BZR_PLUGIN_PATH`` they should be separated by the
93
 
platform specific appropriate character (':' on Unix/Linux/etc,
 
95
platform specific appropriate character (':' on Unix,
94
96
';' on windows)
95
97
 
96
98
By default if ``BZR_PLUGIN_PATH`` is set, it replaces searching
130
132
 
131
133
  BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user
132
134
 
133
 
BZR_DISABLE_PLUGINS
 
135
BRZ_DISABLE_PLUGINS
134
136
~~~~~~~~~~~~~~~~~~~
135
137
 
136
138
Under special circumstances (mostly when trying to diagnose a
146
148
 
147
149
  BZR_DISABLE_PLUGINS='myplugin:yourplugin'
148
150
 
149
 
BZR_PLUGINS_AT
 
151
BRZ_PLUGINS_AT
150
152
~~~~~~~~~~~~~~
151
153
 
152
154
When adding a new feature or working on a bug in a plugin,
173
175
Using a specific version of ``myplugin``:
174
176
``BZR_PLUGINS_AT='myplugin@/home/me/bugfixes/123456-myplugin``
175
177
 
176
 
BZRPATH
 
178
BRZPATH
177
179
~~~~~~~
178
180
 
179
 
The path where Bazaar should look for shell plugin external commands.
 
181
The path where Breezy should look for shell plugin external commands.
 
182
 
 
183
 
 
184
http_proxy, https_proxy
 
185
~~~~~~~~~~~~~~~~~~~~~~~
 
186
 
 
187
Specifies the network proxy for outgoing connections, for example::
 
188
 
 
189
  http_proxy=http://proxy.example.com:3128/ 
 
190
  https_proxy=http://proxy.example.com:3128/
180
191
 
181
192
 
182
193
Configuration files
185
196
Location
186
197
~~~~~~~~
187
198
 
188
 
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
189
 
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
 
199
Configuration files are located in ``$HOME/.bazaar`` on Unix and
 
200
``C:\Documents and Settings\<username>\Application Data\Breezy\2.0`` on
190
201
Windows. (You can check the location for your system by using
191
202
``bzr version``.)
192
203
 
193
204
There are three primary configuration files in this location:
194
205
 
195
 
* ``bazaar.conf`` describes default configuration options,
 
206
* ``breezy.conf`` describes default configuration options,
196
207
 
197
208
* ``locations.conf`` describes configuration information for
198
209
  specific branch locations,
210
221
~~~~~~~~~~~~~~
211
222
 
212
223
An ini file has three types of contructs: section headers, section
213
 
variables and comments.
 
224
options and comments.
214
225
 
215
226
Comments
216
227
^^^^^^^^
217
228
 
218
229
A comment is any line that starts with a "#" (sometimes called a "hash
219
230
mark", "pound sign" or "number sign"). Comment lines are ignored by
220
 
Bazaar when parsing ini files.
 
231
Breezy when parsing ini files.
221
232
 
222
233
Section headers
223
234
^^^^^^^^^^^^^^^
227
238
 
228
239
    [DEFAULT]
229
240
 
230
 
The only valid section headers for bazaar.conf currently are [DEFAULT] and
 
241
The only valid section headers for breezy.conf currently are [DEFAULT] and
231
242
[ALIASES].  Section headers are case sensitive. The default section provides for
232
 
setting variables which can be overridden with the branch config file.
 
243
setting options which can be overridden with the branch config file.
233
244
 
234
 
For ``locations.conf``, the variables from the section with the
 
245
For ``locations.conf``, the options from the section with the
235
246
longest matching section header are used to the exclusion of other
236
247
potentially valid section headers. A section header uses the path for
237
248
the branch as the section header. Some examples include::
240
251
    [/home/jdoe/branches/]
241
252
 
242
253
 
243
 
Section variables
244
 
^^^^^^^^^^^^^^^^^
 
254
Section options
 
255
^^^^^^^^^^^^^^^
245
256
 
246
 
A section variable resides within a section. A section variable contains a
247
 
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::
248
259
 
249
260
    email            = John Doe <jdoe@isp.com>
250
 
    check_signatures = require
251
 
 
252
 
 
253
 
Variable policies
254
 
^^^^^^^^^^^^^^^^^
255
 
 
256
 
Variables defined in a section affect the named directory or URL plus
257
 
any locations they contain.  Policies can be used to change how a
258
 
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
259
275
there are three policies available:
260
276
 
261
277
 none:
268
284
   for contained locations, any additional path components are
269
285
   appended to the value.
270
286
 
271
 
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".
272
288
For example, to define the push location for a tree of branches, the
273
289
following could be used::
274
290
 
279
295
With this configuration, the push location for ``/top/location/branch1``
280
296
would be ``sftp://example.com/location/branch1``.
281
297
 
282
 
 
283
 
The main configuration file, bazaar.conf
 
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
284
354
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285
355
 
286
 
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
 
356
``breezy.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
287
357
The default section contains the default
288
358
configuration options for all branches. The default section can be
289
359
overriden by providing a branch-specific section in ``locations.conf``.
290
360
 
291
 
A typical ``bazaar.conf`` section often looks like the following::
 
361
A typical ``breezy.conf`` section often looks like the following::
292
362
 
293
363
    [DEFAULT]
294
364
    email             = John Doe <jdoe@isp.com>
295
365
    editor            = /usr/bin/vim
296
 
    check_signatures  = check-available
297
366
    create_signatures = when-required
298
367
 
299
368
 
302
371
 
303
372
``locations.conf`` allows one to specify overriding settings for
304
373
a specific branch. The format is almost identical to the default section in
305
 
bazaar.conf with one significant change: The section header, instead of saying
 
374
breezy.conf with one significant change: The section header, instead of saying
306
375
default, will be the path to a branch that you wish to override a value
307
376
for. The '?' and '*' wildcards are supported::
308
377
 
311
380
 
312
381
    [http://hypothetical.site.com/branches/devel-branch]
313
382
    create_signatures = always
314
 
    check_signatures  = always
315
 
 
316
 
    [http://bazaar-vcs.org/bzr/*]
317
 
    check_signatures  = require
318
383
 
319
384
The authentication configuration file, authentication.conf
320
385
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
324
389
of bzr that requires authentication (smtp for example).
325
390
 
326
391
The syntax of the file obeys the same rules as the others except for the
327
 
variable policies which don't apply.
 
392
option policies which don't apply.
328
393
 
329
394
For more information on the possible uses of the authentication configuration
330
395
file see :doc:`authentication-help`.
331
396
 
332
397
 
333
 
Common variable options
334
 
-----------------------
 
398
Common options
 
399
--------------
335
400
 
336
401
debug_flags
337
402
~~~~~~~~~~~
342
407
 
343
408
    debug_flags = hpss
344
409
 
 
410
or::
 
411
 
 
412
    debug_flags = hpss,evil
 
413
 
345
414
email
346
415
~~~~~
347
416
 
368
437
check_signatures
369
438
~~~~~~~~~~~~~~~~
370
439
 
371
 
Defines the behavior for signatures.
 
440
Reserved for future use.  These options will allow a policy for branches to
 
441
require signatures.
372
442
 
373
443
require
374
444
    The gnupg signature for revisions must be present and must be valid.
378
448
 
379
449
check-available
380
450
    (default) If gnupg signatures for revisions are present, check them.
381
 
    Bazaar will fail if it finds a bad signature, but will not fail if
 
451
    Breezy will fail if it finds a bad signature, but will not fail if
382
452
    no signature is present.
383
453
 
384
454
create_signatures
385
455
~~~~~~~~~~~~~~~~~
386
456
 
387
 
Defines the behaviour of signing revisions.
 
457
Defines the behaviour of signing revisions on commits.  By default bzr will not
 
458
sign new commits.
388
459
 
389
460
always
390
 
    Sign every new revision that is committed.
 
461
    Sign every new revision that is committed.  If the signing fails then the
 
462
    commit will not be made.
391
463
 
392
464
when-required
393
 
    (default) Sign newly committed revisions only when the branch requires
394
 
    signed revisions.
 
465
    Reserved for future use.
395
466
 
396
467
never
397
 
    Refuse to sign newly committed revisions, even if the branch
398
 
    requires signatures.
 
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``.
399
487
 
400
488
recurse
401
489
~~~~~~~
410
498
    This section only applies to the branch at this directory and not
411
499
    branches below it.
412
500
 
413
 
gpg_signing_command
414
 
~~~~~~~~~~~~~~~~~~~
415
 
 
416
 
(Default: "gpg"). Which program should be used to sign and check revisions.
417
 
For example::
418
 
 
419
 
    gpg_signing_command = /usr/bin/gnpg
420
 
 
421
501
bzr_remote_path
422
502
~~~~~~~~~~~~~~~
423
503
 
433
513
smtp_server
434
514
~~~~~~~~~~~
435
515
 
436
 
(Default: "localhost"). SMTP server to use when Bazaar needs to send
 
516
(Default: "localhost"). SMTP server to use when Breezy needs to send
437
517
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
438
518
 
439
519
smtp_username, smtp_password
440
520
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
441
521
 
442
522
User and password to authenticate to the SMTP server. If smtp_username
443
 
is set, and smtp_password is not, Bazaar will prompt for a password.
 
523
is set, and smtp_password is not, Breezy will prompt for a password.
444
524
These settings are only needed if the SMTP server requires authentication
445
525
to send mail.
446
526
 
 
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
 
447
535
mail_client
448
536
~~~~~~~~~~~
449
537
 
470
558
:mapi: Use your preferred e-mail client on Windows.
471
559
:xdg-email: Use xdg-email to run your preferred mail program
472
560
 
 
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
 
473
568
submit_branch
474
569
~~~~~~~~~~~~~
475
570
 
495
590
    whether the format deprecation warning is shown on repositories that are
496
591
    using deprecated formats.
497
592
 
 
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
 
 
604
Unicode options
 
605
---------------
 
606
 
 
607
output_encoding
 
608
~~~~~~~~~~~~~~~
 
609
 
 
610
A Python unicode encoding name for text output from bzr, such as log
 
611
information.  Values include: utf8, cp850, ascii, iso-8859-1.  The default
 
612
is the terminal encoding prefered by the operating system.
 
613
 
498
614
 
499
615
Branch type specific options
500
616
----------------------------
502
618
These options apply only to branches that use the ``dirstate-tags`` or
503
619
later format.  They
504
620
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
505
 
manually set in ``locations.conf`` or ``bazaar.conf``.
 
621
manually set in ``locations.conf`` or ``breezy.conf``.
506
622
 
507
623
append_revisions_only
508
624
~~~~~~~~~~~~~~~~~~~~~
517
633
parent_location
518
634
~~~~~~~~~~~~~~~
519
635
 
520
 
If present, the location of the default branch for pull or merge.
521
 
This option is normally set by ``pull --remember`` or ``merge
 
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
522
638
--remember``.
523
639
 
524
640
push_location
525
641
~~~~~~~~~~~~~
526
642
 
527
643
If present, the location of the default branch for push.  This option
528
 
is normally set by ``push --remember``.
 
644
is normally set by the first ``push`` or ``push --remember``.
529
645
 
530
646
push_strict
531
647
~~~~~~~~~~~
533
649
If present, defines the ``--strict`` option default value for checking
534
650
uncommitted changes before pushing.
535
651
 
536
 
dpush_strict
537
 
~~~~~~~~~~~~
538
 
 
539
 
If present, defines the ``--strict`` option default value for checking
540
 
uncommitted changes before pushing into a different VCS without any
541
 
custom bzr metadata.
542
 
 
543
652
bound_location
544
653
~~~~~~~~~~~~~~
545
654
 
558
667
If present, defines the ``--strict`` option default value for checking
559
668
uncommitted changes before sending a merge directive.
560
669
 
 
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