← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/configuration.txt

(mbp) merge bzr.dev to 0.8, prepare for release

Show diffs side-by-side

added added

removed removed

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