/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: Breezy landing bot
  • Author(s): Jelmer Vernooij
  • Date: 2018-07-04 12:50:55 UTC
  • mfrom: (7027.2.8 git-fixes)
  • Revision ID: breezy.the.bot@gmail.com-20180704125055-8nni25pn2439p48v
Fix eol handling in knits on Python 3, port fastimport plugin to Python 3.

Merged from https://code.launchpad.net/~jelmer/brz/fastimport-fixes/+merge/348924

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.
61
 
 
62
 
BZR_PLUGIN_PATH
 
62
Path to the editor Breezy should use for commit messages, etc.
 
63
 
 
64
BRZ_LOG
 
65
~~~~~~~
 
66
 
 
67
Location of the Breezy log file. You can check the current location by
 
68
running ``bzr version``.
 
69
 
 
70
The log file contains debug information that is useful for diagnosing or
 
71
reporting problems with Breezy.
 
72
 
 
73
Setting this to ``NUL`` on Windows or ``/dev/null`` on other platforms
 
74
will disable logging.
 
75
 
 
76
 
 
77
BRZ_PLUGIN_PATH
63
78
~~~~~~~~~~~~~~~
64
79
 
65
 
The path to the plugins directory that Bazaar should use.
66
 
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:
67
82
 
68
83
* the user specific plugin directory (containing the ``user`` plugins),
69
84
 
70
 
* the bzrlib directory (containing the ``core`` plugins),
 
85
* the breezy directory (containing the ``core`` plugins),
71
86
 
72
87
* the site specific plugin directory if applicable (containing
73
88
  the ``site`` plugins).
77
92
 
78
93
As for the ``PATH`` variables, if multiple directories are
79
94
specified in ``BZR_PLUGIN_PATH`` they should be separated by the
80
 
platform specific appropriate character (':' on Unix/Linux/etc,
 
95
platform specific appropriate character (':' on Unix,
81
96
';' on windows)
82
97
 
83
98
By default if ``BZR_PLUGIN_PATH`` is set, it replaces searching
117
132
 
118
133
  BZR_PLUGIN_PATH='/path/to/my/site/plugins:-site':+user
119
134
 
120
 
BZR_DISABLE_PLUGINS
 
135
BRZ_DISABLE_PLUGINS
121
136
~~~~~~~~~~~~~~~~~~~
122
137
 
123
138
Under special circumstances (mostly when trying to diagnose a
133
148
 
134
149
  BZR_DISABLE_PLUGINS='myplugin:yourplugin'
135
150
 
136
 
BZR_PLUGINS_AT
 
151
BRZ_PLUGINS_AT
137
152
~~~~~~~~~~~~~~
138
153
 
139
154
When adding a new feature or working on a bug in a plugin,
160
175
Using a specific version of ``myplugin``:
161
176
``BZR_PLUGINS_AT='myplugin@/home/me/bugfixes/123456-myplugin``
162
177
 
163
 
BZRPATH
 
178
BRZPATH
164
179
~~~~~~~
165
180
 
166
 
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/
167
191
 
168
192
 
169
193
Configuration files
172
196
Location
173
197
~~~~~~~~
174
198
 
175
 
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
176
 
``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
177
201
Windows. (You can check the location for your system by using
178
202
``bzr version``.)
179
203
 
180
204
There are three primary configuration files in this location:
181
205
 
182
 
* ``bazaar.conf`` describes default configuration options,
 
206
* ``breezy.conf`` describes default configuration options,
183
207
 
184
208
* ``locations.conf`` describes configuration information for
185
209
  specific branch locations,
197
221
~~~~~~~~~~~~~~
198
222
 
199
223
An ini file has three types of contructs: section headers, section
200
 
variables and comments.
 
224
options and comments.
201
225
 
202
226
Comments
203
227
^^^^^^^^
204
228
 
205
229
A comment is any line that starts with a "#" (sometimes called a "hash
206
230
mark", "pound sign" or "number sign"). Comment lines are ignored by
207
 
Bazaar when parsing ini files.
 
231
Breezy when parsing ini files.
208
232
 
209
233
Section headers
210
234
^^^^^^^^^^^^^^^
214
238
 
215
239
    [DEFAULT]
216
240
 
217
 
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
218
242
[ALIASES].  Section headers are case sensitive. The default section provides for
219
 
setting variables which can be overridden with the branch config file.
 
243
setting options which can be overridden with the branch config file.
220
244
 
221
 
For ``locations.conf``, the variables from the section with the
 
245
For ``locations.conf``, the options from the section with the
222
246
longest matching section header are used to the exclusion of other
223
247
potentially valid section headers. A section header uses the path for
224
248
the branch as the section header. Some examples include::
227
251
    [/home/jdoe/branches/]
228
252
 
229
253
 
230
 
Section variables
231
 
^^^^^^^^^^^^^^^^^
 
254
Section options
 
255
^^^^^^^^^^^^^^^
232
256
 
233
 
A section variable resides within a section. A section variable contains a
234
 
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::
235
259
 
236
260
    email            = John Doe <jdoe@isp.com>
237
 
    check_signatures = require
238
 
 
239
 
 
240
 
Variable policies
241
 
^^^^^^^^^^^^^^^^^
242
 
 
243
 
Variables defined in a section affect the named directory or URL plus
244
 
any locations they contain.  Policies can be used to change how a
245
 
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
246
275
there are three policies available:
247
276
 
248
277
 none:
255
284
   for contained locations, any additional path components are
256
285
   appended to the value.
257
286
 
258
 
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".
259
288
For example, to define the push location for a tree of branches, the
260
289
following could be used::
261
290
 
266
295
With this configuration, the push location for ``/top/location/branch1``
267
296
would be ``sftp://example.com/location/branch1``.
268
297
 
269
 
 
270
 
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
271
354
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272
355
 
273
 
``bazaar.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
 
356
``breezy.conf`` allows two sections: ``[DEFAULT]`` and ``[ALIASES]``.
274
357
The default section contains the default
275
358
configuration options for all branches. The default section can be
276
359
overriden by providing a branch-specific section in ``locations.conf``.
277
360
 
278
 
A typical ``bazaar.conf`` section often looks like the following::
 
361
A typical ``breezy.conf`` section often looks like the following::
279
362
 
280
363
    [DEFAULT]
281
364
    email             = John Doe <jdoe@isp.com>
282
365
    editor            = /usr/bin/vim
283
 
    check_signatures  = check-available
284
366
    create_signatures = when-required
285
367
 
286
368
 
289
371
 
290
372
``locations.conf`` allows one to specify overriding settings for
291
373
a specific branch. The format is almost identical to the default section in
292
 
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
293
375
default, will be the path to a branch that you wish to override a value
294
376
for. The '?' and '*' wildcards are supported::
295
377
 
298
380
 
299
381
    [http://hypothetical.site.com/branches/devel-branch]
300
382
    create_signatures = always
301
 
    check_signatures  = always
302
 
 
303
 
    [http://bazaar-vcs.org/bzr/*]
304
 
    check_signatures  = require
305
383
 
306
384
The authentication configuration file, authentication.conf
307
385
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311
389
of bzr that requires authentication (smtp for example).
312
390
 
313
391
The syntax of the file obeys the same rules as the others except for the
314
 
variable policies which don't apply.
 
392
option policies which don't apply.
315
393
 
316
394
For more information on the possible uses of the authentication configuration
317
395
file see :doc:`authentication-help`.
318
396
 
319
397
 
320
 
Common variable options
321
 
-----------------------
 
398
Common options
 
399
--------------
322
400
 
323
401
debug_flags
324
402
~~~~~~~~~~~
329
407
 
330
408
    debug_flags = hpss
331
409
 
 
410
or::
 
411
 
 
412
    debug_flags = hpss,evil
 
413
 
332
414
email
333
415
~~~~~
334
416
 
355
437
check_signatures
356
438
~~~~~~~~~~~~~~~~
357
439
 
358
 
Defines the behavior for signatures.
 
440
Reserved for future use.  These options will allow a policy for branches to
 
441
require signatures.
359
442
 
360
443
require
361
444
    The gnupg signature for revisions must be present and must be valid.
365
448
 
366
449
check-available
367
450
    (default) If gnupg signatures for revisions are present, check them.
368
 
    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
369
452
    no signature is present.
370
453
 
371
454
create_signatures
372
455
~~~~~~~~~~~~~~~~~
373
456
 
374
 
Defines the behaviour of signing revisions.
 
457
Defines the behaviour of signing revisions on commits.  By default bzr will not
 
458
sign new commits.
375
459
 
376
460
always
377
 
    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.
378
463
 
379
464
when-required
380
 
    (default) Sign newly committed revisions only when the branch requires
381
 
    signed revisions.
 
465
    Reserved for future use.
382
466
 
383
467
never
384
 
    Refuse to sign newly committed revisions, even if the branch
385
 
    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``.
386
487
 
387
488
recurse
388
489
~~~~~~~
397
498
    This section only applies to the branch at this directory and not
398
499
    branches below it.
399
500
 
400
 
gpg_signing_command
401
 
~~~~~~~~~~~~~~~~~~~
402
 
 
403
 
(Default: "gpg"). Which program should be used to sign and check revisions.
404
 
For example::
405
 
 
406
 
    gpg_signing_command = /usr/bin/gnpg
407
 
 
408
501
bzr_remote_path
409
502
~~~~~~~~~~~~~~~
410
503
 
420
513
smtp_server
421
514
~~~~~~~~~~~
422
515
 
423
 
(Default: "localhost"). SMTP server to use when Bazaar needs to send
 
516
(Default: "localhost"). SMTP server to use when Breezy needs to send
424
517
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.
425
518
 
426
519
smtp_username, smtp_password
427
520
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
428
521
 
429
522
User and password to authenticate to the SMTP server. If smtp_username
430
 
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.
431
524
These settings are only needed if the SMTP server requires authentication
432
525
to send mail.
433
526
 
 
527
locks.steal_dead
 
528
~~~~~~~~~~~~~~~~
 
529
 
 
530
If set to true, bzr will automatically break locks held by processes from
 
531
the same machine and user that are no longer alive.  Otherwise, 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
 
434
535
mail_client
435
536
~~~~~~~~~~~
436
537
 
457
558
:mapi: Use your preferred e-mail client on Windows.
458
559
:xdg-email: Use xdg-email to run your preferred mail program
459
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
 
460
568
submit_branch
461
569
~~~~~~~~~~~~~
462
570
 
482
590
    whether the format deprecation warning is shown on repositories that are
483
591
    using deprecated formats.
484
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
 
485
614
 
486
615
Branch type specific options
487
616
----------------------------
489
618
These options apply only to branches that use the ``dirstate-tags`` or
490
619
later format.  They
491
620
are usually set in ``.bzr/branch/branch.conf`` automatically, but may be
492
 
manually set in ``locations.conf`` or ``bazaar.conf``.
 
621
manually set in ``locations.conf`` or ``breezy.conf``.
493
622
 
494
623
append_revisions_only
495
624
~~~~~~~~~~~~~~~~~~~~~
504
633
parent_location
505
634
~~~~~~~~~~~~~~~
506
635
 
507
 
If present, the location of the default branch for pull or merge.
508
 
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
509
638
--remember``.
510
639
 
511
640
push_location
512
641
~~~~~~~~~~~~~
513
642
 
514
643
If present, the location of the default branch for push.  This option
515
 
is normally set by ``push --remember``.
 
644
is normally set by the first ``push`` or ``push --remember``.
516
645
 
517
646
push_strict
518
647
~~~~~~~~~~~
545
674
If present, defines the ``--strict`` option default value for checking
546
675
uncommitted changes before sending a merge directive.
547
676
 
 
677
add.maximum_file_size
 
678
~~~~~~~~~~~~~~~~~~~~~
 
679
 
 
680
Defines the maximum file size the command line "add" operation will allow
 
681
in recursive mode, with files larger than this value being skipped. You may 
 
682
specify this value as an integer (in which case it is interpreted as bytes), 
 
683
or you may specify the value using SI units, i.e. 10KB, 20MB, 1G. A value of 0 
 
684
will disable skipping.
 
685
 
 
686
External Merge Tools
 
687
--------------------
 
688
 
 
689
bzr.mergetool.<name>
 
690
~~~~~~~~~~~~~~~~~~~~
 
691
 
 
692
Defines an external merge tool called <name> with the given command-line.
 
693
Arguments containing spaces should be quoted using single or double quotes. The
 
694
executable may omit its path if it can be found on the PATH.
 
695
 
 
696
The following markers can be used in the command-line to substitute filenames
 
697
involved in the merge conflict::
 
698
 
 
699
  {base}      file.BASE
 
700
  {this}      file.THIS
 
701
  {other}     file.OTHER
 
702
  {result}    output file
 
703
  {this_temp} temp copy of file.THIS, used to overwrite output file if merge
 
704
              succeeds.
 
705
 
 
706
For example::
 
707
 
 
708
  bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
709
 
 
710
Because ``mergetool`` and ``config`` itself both use curly braces as
 
711
interpolation markers, trying to display the mergetool line results in the
 
712
following problem::
 
713
 
 
714
 
 
715
  $ bzr config bzr.mergetool.kdiff3='kdiff3 {base} {this} {other} -o {result}'
 
716
  $ bzr config bzr.mergetool.kdiff3
 
717
  bzr: ERROR: Option base is not defined while expanding "kdiff3 {base} {this} {other} -o {result}".
 
718
 
 
719
To avoid this, ``config`` can be instructed not to try expanding variables::
 
720
 
 
721
  $ bzr config --all bzr.mergetool.kdiff3
 
722
  branch:
 
723
    bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
724
 
 
725
 
 
726
bzr.default_mergetool
 
727
~~~~~~~~~~~~~~~~~~~~~
 
728
 
 
729
Specifies which external merge tool (as defined above) should be selected by
 
730
default in tools such as ``bzr qconflicts``.
 
731
 
 
732
For example::
 
733
 
 
734
  bzr.default_mergetool = kdiff3