1861.2.6
by Alexander Belchenko
branding: change Bazaar-NG to Bazaar |
1 |
==================== |
2 |
Bazaar configuration |
|
3 |
==================== |
|
1821.1.1
by Alexander Belchenko
win32 installer for bzr.dev.0.9 |
4 |
|
1861.2.6
by Alexander Belchenko
branding: change Bazaar-NG to Bazaar |
5 |
Information on how to configure Bazaar. |
1821.1.1
by Alexander Belchenko
win32 installer for bzr.dev.0.9 |
6 |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
7 |
Location of configuration file |
8 |
============================== |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
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. These files are sometimes referred to as ``ini files``. |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
13 |
|
14 |
General Format |
|
15 |
============== |
|
16 |
An ini file has three types of contructs: section headers, section |
|
17 |
variables and comments. |
|
18 |
||
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
19 |
Comments |
20 |
-------- |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
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 |
|
1861.2.6
by Alexander Belchenko
branding: change Bazaar-NG to Bazaar |
23 |
Bazaar when parsing ini files. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
24 |
|
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
25 |
Section Headers |
26 |
--------------- |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
27 |
A section header is a word enclosed in brackets that starts at the begining |
2293.1.6
by Brad Crittenden
post review changes |
28 |
of a line. A typical section header looks like this:: |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
29 |
|
30 |
[DEFAULT] |
|
31 |
||
2293.1.6
by Brad Crittenden
post review changes |
32 |
The only valid section header for bazaar.conf is [DEFAULT], which is |
33 |
case sensitive. The default section provides for setting variables |
|
34 |
which can be overridden with the branch config file. |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
35 |
|
2293.1.6
by Brad Crittenden
post review changes |
36 |
For ``locations.conf``, the variables from the section with the |
37 |
longest matching section header are used to the exclusion of other |
|
38 |
potentially valid section headers. A section header uses the path for |
|
39 |
the branch as the section header. Some examples include:: |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
40 |
|
41 |
[http://mybranches.isp.com/~jdoe/branchdir] |
|
42 |
[/home/jdoe/branches/] |
|
43 |
||
44 |
||
45 |
||
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
46 |
Section Variables |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
47 |
----------------- |
48 |
||
49 |
A section variable resides within a section. A section variable contains a |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
50 |
variable name, an equals sign and a value. For example:: |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
51 |
|
52 |
email = John Doe <jdoe@isp.com> |
|
53 |
check_signatures = require |
|
54 |
||
55 |
||
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
56 |
Variable Policies |
2120.6.13
by James Henstridge
update doc/configuration.txt with information about policies |
57 |
----------------- |
58 |
||
59 |
Variables defined in a section affect the named directory or URL plus |
|
60 |
any locations they contain. Policies can be used to change how a |
|
61 |
variable value is interpreted for contained locations. Currently |
|
62 |
there are three policies available: |
|
63 |
||
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
64 |
none: |
65 |
the value is interpreted the same for contained locations. This is |
|
66 |
the default behaviour. |
|
67 |
norecurse: |
|
68 |
the value is only used for the exact location specified by the |
|
69 |
section name. |
|
70 |
appendpath: |
|
71 |
for contained locations, any additional path components are |
|
72 |
appended to the value. |
|
2120.6.13
by James Henstridge
update doc/configuration.txt with information about policies |
73 |
|
74 |
Policies are specified by keys with names of the form "$var:policy". |
|
75 |
For example, to define the push location for a tree of branches, the |
|
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
76 |
following could be used:: |
2120.6.13
by James Henstridge
update doc/configuration.txt with information about policies |
77 |
|
78 |
[/top/location] |
|
79 |
push_location = sftp://example.com/location |
|
80 |
push_location:policy = appendpath |
|
81 |
||
2120.6.14
by James Henstridge
Fix RST syntax as suggested by j-a-meinel |
82 |
With this configuration, the push location for ``/top/location/branch1`` |
83 |
would be ``sftp://example.com/location/branch1``. |
|
2120.6.13
by James Henstridge
update doc/configuration.txt with information about policies |
84 |
|
85 |
||
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
86 |
The main configuration file, bazaar.conf |
87 |
---------------------------------------- |
|
88 |
||
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
89 |
The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one |
90 |
section called ``[DEFAULT]``. This default section contains the default |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
91 |
configuration options for all branches. The default section can be |
2293.1.6
by Brad Crittenden
post review changes |
92 |
overriden by providing a branch-specific section in ``locations.conf``. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
93 |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
94 |
A typical ``bazaar.conf`` section often looks like the following:: |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
95 |
|
96 |
[DEFAULT] |
|
97 |
email = John Doe <jdoe@isp.com> |
|
98 |
editor = /usr/bin/vim |
|
99 |
check_signatures = check-available |
|
100 |
create_signatures = when-required |
|
101 |
||
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
102 |
``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for a |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
103 |
specific branch. The format is almost identical to the default section in |
104 |
bazaar.conf with one significant change: The section header, instead of |
|
105 |
saying default, will be the path to a branch that you wish to override a |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
106 |
value for. The '?' and '*' wildcards are supported:: |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
107 |
|
108 |
[/home/jdoe/branches/nethack] |
|
109 |
email = Nethack Admin <nethack@nethack.com> |
|
110 |
||
111 |
[http://hypothetical.site.com/branches/devel-branch] |
|
112 |
create_signatures = always |
|
113 |
check_signatures = always |
|
114 |
||
1861.2.8
by Alexander Belchenko
More branding: bazaar-ng -> Bazaar; bazaar-ng.org -> bazaar-vcs.org |
115 |
[http://bazaar-vcs.org/bzr/*] |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
116 |
check_signatures = require |
117 |
||
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
118 |
Common Variable Options |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
119 |
======================= |
120 |
||
121 |
||
122 |
----- |
|
123 |
The email address to use when committing a branch. Typically takes the form |
|
124 |
of:: |
|
125 |
||
126 |
email = Full Name <account@hostname.tld> |
|
127 |
||
128 |
editor |
|
129 |
------ |
|
130 |
The path of the editor that you wish to use if *bzr commit* is run without |
|
2135.1.1
by Matthew Fuller
Correct statement about the precedence of $EDITOR, and mention |
131 |
a commit log message. This setting is trumped by the environment variable |
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
132 |
``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
133 |
|
134 |
check_signatures |
|
135 |
---------------- |
|
136 |
Defines the behavior for signatures. |
|
137 |
||
138 |
require |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
139 |
The gnupg signature for revisions must be present and must be valid. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
140 |
|
141 |
ignore |
|
2376.4.35
by Jonathan Lange
Include configuration documentation for tracker config options. |
142 |
Do not check gnupg signatures of revisions. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
143 |
|
144 |
check-available |
|
145 |
(default) If gnupg signatures for revisions are present, check them. |
|
1861.2.6
by Alexander Belchenko
branding: change Bazaar-NG to Bazaar |
146 |
Bazaar will fail if it finds a bad signature, but will not fail if |
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
147 |
no signature is present. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
148 |
|
149 |
create_signatures |
|
150 |
----------------- |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
151 |
Defines the behaviour of signing revisions. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
152 |
|
153 |
always |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
154 |
Sign every new revision that is committed. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
155 |
|
156 |
when-required |
|
157 |
(default) Sign newly committed revisions only when the branch requires |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
158 |
signed revisions. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
159 |
|
160 |
never |
|
2293.1.6
by Brad Crittenden
post review changes |
161 |
Refuse to sign newly committed revisions, even if the branch |
162 |
requires signatures. |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
163 |
|
164 |
recurse |
|
165 |
------- |
|
2293.1.6
by Brad Crittenden
post review changes |
166 |
Only useful in ``locations.conf``. Defines whether or not the |
167 |
configuration for this section applies to subdirectories: |
|
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
168 |
|
169 |
true |
|
2293.1.6
by Brad Crittenden
post review changes |
170 |
(default) This section applies to subdirectories as well. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
171 |
|
172 |
false |
|
173 |
This section only applies to the branch at this directory and not |
|
2376.4.35
by Jonathan Lange
Include configuration documentation for tracker config options. |
174 |
branches below it. |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
175 |
|
176 |
gpg_signing_command |
|
177 |
------------------- |
|
178 |
(Default: "gpg"). Which program should be used to sign and check revisions. |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
179 |
For example:: |
1610.2.1
by James Blackwell
Copied in docs for wiki & First round cleanup |
180 |
|
181 |
gpg_signing_command = /usr/bin/gnpg |
|
182 |
||
2535.2.1
by Adeodato Simó
New SMTPConnection class, a reduced version of that in bzr-email. |
183 |
smtp_server |
184 |
----------- |
|
185 |
(Default: "localhost"). SMTP server to use when Bazaar needs to send |
|
186 |
email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin. |
|
187 |
||
188 |
smtp_username, smtp_password |
|
189 |
---------------------------- |
|
190 |
User and password to authenticate to the SMTP server. If smtp_username |
|
191 |
is set, and smtp_password is not, Bazaar will prompt for a password. |
|
192 |
||
2230.3.43
by Aaron Bentley
Update docs |
193 |
|
194 |
Branch 6 Options |
|
195 |
================ |
|
196 |
||
197 |
These options apply only to branches that use the "experimental-branch6" |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
198 |
format. They are usually set in ``.bzr/branch/branch.conf`` automatically, but |
199 |
may be manually set in ``locations.conf`` or ``bazaar.conf``. |
|
2230.3.43
by Aaron Bentley
Update docs |
200 |
|
201 |
append_revisions_only |
|
202 |
--------------------- |
|
2293.1.6
by Brad Crittenden
post review changes |
203 |
If set to "True" then revisions can only be appended to the log, not |
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
204 |
removed. A branch with this setting enabled can only pull from |
205 |
another branch if the other branch's log is a longer version of its |
|
206 |
own. This is normally set by ``bzr init --append-revisions-only``. |
|
2230.3.43
by Aaron Bentley
Update docs |
207 |
|
208 |
parent_location |
|
209 |
--------------- |
|
210 |
If present, the location of the default branch for pull or merge. |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
211 |
This option is normally set by ``pull --remember`` or ``merge |
212 |
--remember`` |
|
2230.3.43
by Aaron Bentley
Update docs |
213 |
|
214 |
push_location |
|
215 |
------------- |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
216 |
If present, the location of the default branch for push. This option |
217 |
is normally set by ``push --remember``. |
|
2230.3.43
by Aaron Bentley
Update docs |
218 |
|
219 |
bound_location |
|
220 |
-------------- |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
221 |
The location that commits should go to when acting as a checkout. |
222 |
This option is normally set by ``bind``. |
|
2230.3.43
by Aaron Bentley
Update docs |
223 |
|
224 |
bound |
|
225 |
----- |
|
226 |
If set to "True", the branch should act as a checkout, and push each commit to |
|
2293.1.3
by Brad Crittenden
Updated version_info.txt for grammar changes |
227 |
the bound_location. This option is normally set by ``bind``/``unbind``. |
2376.4.35
by Jonathan Lange
Include configuration documentation for tracker config options. |
228 |
|
229 |
||
230 |
Bug Tracker Options |
|
231 |
=================== |
|
232 |
||
2376.4.39
by Jonathan Lange
Can also set the bug config options in branch.conf |
233 |
These options can go into bazaar.conf, branch.conf or into a branch-specific |
234 |
configuration section in locations.conf. |
|
2376.4.35
by Jonathan Lange
Include configuration documentation for tracker config options. |
235 |
|
236 |
bugzilla_<tracker_abbreviation>_url |
|
237 |
----------------------------------- |
|
238 |
If present, the location of the Bugzilla bug tracker referred to by |
|
239 |
<tracker_abbreviation>. This option can then be used together with ``bzr commit |
|
240 |
--fixes`` to mark bugs in that tracker as being fixed by that commit. For |
|
241 |
example:: |
|
242 |
||
243 |
bugzilla_squid_url = http://www.squid-cache.org/bugs |
|
244 |
||
245 |
would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as |
|
246 |
fixed. |
|
247 |
||
248 |
trac_<tracker_abbrevation>_url |
|
249 |
------------------------------ |
|
250 |
If present, the location of the Trac instance referred to by |
|
251 |
<tracker_abbreviation>. This option can then be used together with ``bzr commit |
|
252 |
--fixes`` to mark bugs in that tracker as being fixed by that commit. For |
|
253 |
example:: |
|
254 |
||
255 |
trac_twisted_url = http://www.twistedmatrix.com/trac |
|
256 |
||
257 |
would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as |
|
258 |
fixed. |