← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/configuration.txt

Fix BzrDir.create_workingtree for NULL_REVISION

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
$BZR_EDITOR 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