← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/configuration.txt

merge merge tweaks from aaron, which includes latest .dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/configuration.txt
1
 
====================
2
 
Bazaar configuration
3
 
====================
4
 
 
5
 
Information on how to configure Bazaar.
6
 
 
7
 
Location of configuration file
8
 
==============================
9
 
Each user gets a pair of configurations files in $HOME/.bazaar. The first
10
 
one, named bazaar.conf, includes default configuration options. The other
11
 
file, locations.conf, contains configuration information for specific
12
 
branch locations.
13
 
 
14
 
General Format
15
 
==============
16
 
An ini file has three types of contructs: section headers, section
17
 
variables and comments.
18
 
 
19
 
comment
20
 
-------
21
 
A comment is any line that starts with a "#" (sometimes called a "hash
22
 
mark", "pound sign" or "number sign"). Comment lines are ignored by
23
 
Bazaar when parsing ini files.
24
 
 
25
 
section header
26
 
--------------
27
 
A section header is a word enclosed in brackets that starts at the begining
28
 
of a line, typical section headers look like this::
29
 
 
30
 
    [DEFAULT]
31
 
 
32
 
The only valid section header for bazaar.conf is [DEFAULT], which is case
33
 
senstive. The default section provides for setting variables which can be
34
 
overridden with the branch config file.
35
 
 
36
 
For locations.conf, the variables from the section with the longest matching
37
 
section header are used to the exclusion of other potentially valid section
38
 
headers. A section header uses the path for the branch as the section
39
 
header. Some examples include::
40
 
 
41
 
    [http://mybranches.isp.com/~jdoe/branchdir]
42
 
    [/home/jdoe/branches/]
43
 
 
44
 
 
45
 
 
46
 
section variables
47
 
-----------------
48
 
 
49
 
A section variable resides within a section. A section variable contains a
50
 
variable name, an equals sign and a value and generally takes the following
51
 
form::
52
 
 
53
 
    email            = John Doe <jdoe@isp.com>
54
 
    check_signatures = require
55
 
 
56
 
 
57
 
The main configuration file, bazaar.conf
58
 
----------------------------------------
59
 
 
60
 
The main configuration file, $HOME/.bazaar/bazaar.conf, only allows one
61
 
section called '''[DEFAULT]'''. This default section contains the default
62
 
configuration options for all branches. The default section can be
63
 
overriden by providing a branch specific section in locations.conf.
64
 
 
65
 
A typical bazaar.conf section often looks like the following::
66
 
 
67
 
    [DEFAULT]
68
 
    email             = John Doe <jdoe@isp.com>
69
 
    editor            = /usr/bin/vim
70
 
    check_signatures  = check-available
71
 
    create_signatures = when-required
72
 
 
73
 
$HOME/.bazaar/locations.conf allows one to specify overriding settings for a
74
 
specific branch. The format is almost identical to the default section in
75
 
bazaar.conf with one significant change: The section header, instead of
76
 
saying default, will be the path to a branch that you wish to override a
77
 
value for. The ? and * wildcards are supported::
78
 
 
79
 
    [/home/jdoe/branches/nethack]
80
 
    email = Nethack Admin <nethack@nethack.com>
81
 
 
82
 
    [http://hypothetical.site.com/branches/devel-branch]
83
 
    create_signatures = always
84
 
    check_signatures  = always
85
 
 
86
 
    [http://bazaar-vcs.org/bzr/*]
87
 
    check_signatures  = require
88
 
 
89
 
Common Variable options
90
 
=======================
91
 
 
92
 
email
93
 
-----
94
 
The email address to use when committing a branch. Typically takes the form
95
 
of::
96
 
 
97
 
    email = Full Name <account@hostname.tld>
98
 
 
99
 
editor
100
 
------
101
 
The path of the editor that you wish to use if *bzr commit* is run without
102
 
a commit log message. This setting is trumped by the environment variables
103
 
$BZREDITOR or $EDITOR.
104
 
 
105
 
check_signatures
106
 
----------------
107
 
Defines the behavior for signatures.
108
 
 
109
 
require
110
 
    the gnupg signature for revisions must be present and must be valid
111
 
 
112
 
ignore
113
 
    Do not check gnupg signatures of revisions. 
114
 
 
115
 
check-available
116
 
    (default) If gnupg signatures for revisions are present, check them.
117
 
    Bazaar will fail if it finds a bad signature, but will not fail if
118
 
    no signature is present
119
 
 
120
 
create_signatures
121
 
-----------------
122
 
Defines the behaviour of signing revisions. Has three possible values:
123
 
always, never and when-requied.
124
 
 
125
 
always
126
 
    sign every new revision that is committed
127
 
 
128
 
when-required
129
 
    (default) Sign newly committed revisions only when the branch requires
130
 
    signed revisions
131
 
 
132
 
never
133
 
    Refuse to sign newly committed revisions, even if the branch requires signatures
134
 
 
135
 
recurse
136
 
-------
137
 
Only useful in locations.conf. Defines whether or not the configuration for
138
 
this section applies to subdirectories:
139
 
 
140
 
true
141
 
    (default) This section applies to subdirectories as well
142
 
 
143
 
false
144
 
    This section only applies to the branch at this directory and not
145
 
    branches 
146
 
 
147
 
gpg_signing_command
148
 
-------------------
149
 
(Default: "gpg"). Which program should be used to sign and check revisions.
150
 
example::
151
 
 
152
 
    gpg_signing_command = /usr/bin/gnpg
153