← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/configuration.txt

  • Committer: Aaron Bentley
  • Date: 2007-01-11 03:46:53 UTC
  • mto: (2255.6.1 dirstate)
  • mto: This revision was merged to the branch mainline in revision 2322.
  • Revision ID: aaron.bentley@utoronto.ca-20070111034653-wa1n3uy49wbvom5m
Remove get_format_*, make FormatRegistry.register_metadir vary working tree

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
Comments
 
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 Headers
 
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
Variable Policies
 
58
-----------------
 
59
 
 
60
Variables defined in a section affect the named directory or URL plus
 
61
any locations they contain.  Policies can be used to change how a
 
62
variable value is interpreted for contained locations.  Currently
 
63
there are three policies available:
 
64
 
 
65
 none:
 
66
   the value is interpreted the same for contained locations.  This is
 
67
   the default behaviour.
 
68
 norecurse:
 
69
   the value is only used for the exact location specified by the
 
70
   section name.
 
71
 appendpath:
 
72
   for contained locations, any additional path components are
 
73
   appended to the value.
 
74
 
 
75
Policies are specified by keys with names of the form "$var:policy".
 
76
For example, to define the push location for a tree of branches, the
 
77
following could be used::
 
78
 
 
79
  [/top/location]
 
80
  push_location = sftp://example.com/location
 
81
  push_location:policy = appendpath
 
82
 
 
83
With this configuration, the push location for ``/top/location/branch1``
 
84
would be ``sftp://example.com/location/branch1``.
 
85
 
 
86
 
 
87
The main configuration file, bazaar.conf
 
88
----------------------------------------
 
89
 
 
90
The main configuration file, $HOME/.bazaar/bazaar.conf, only allows one
 
91
section called '''[DEFAULT]'''. This default section contains the default
 
92
configuration options for all branches. The default section can be
 
93
overriden by providing a branch specific section in locations.conf.
 
94
 
 
95
A typical bazaar.conf section often looks like the following::
 
96
 
 
97
    [DEFAULT]
 
98
    email             = John Doe <jdoe@isp.com>
 
99
    editor            = /usr/bin/vim
 
100
    check_signatures  = check-available
 
101
    create_signatures = when-required
 
102
 
 
103
$HOME/.bazaar/locations.conf allows one to specify overriding settings for a
 
104
specific branch. The format is almost identical to the default section in
 
105
bazaar.conf with one significant change: The section header, instead of
 
106
saying default, will be the path to a branch that you wish to override a
 
107
value for. The ? and * wildcards are supported::
 
108
 
 
109
    [/home/jdoe/branches/nethack]
 
110
    email = Nethack Admin <nethack@nethack.com>
 
111
 
 
112
    [http://hypothetical.site.com/branches/devel-branch]
 
113
    create_signatures = always
 
114
    check_signatures  = always
 
115
 
 
116
    [http://bazaar-vcs.org/bzr/*]
 
117
    check_signatures  = require
 
118
 
 
119
Common Variable options
 
120
=======================
 
121
 
 
122
email
 
123
-----
 
124
The email address to use when committing a branch. Typically takes the form
 
125
of::
 
126
 
 
127
    email = Full Name <account@hostname.tld>
 
128
 
 
129
editor
 
130
------
 
131
The path of the editor that you wish to use if *bzr commit* is run without
 
132
a commit log message. This setting is trumped by the environment variable
 
133
$BZR_EDITOR, and overrides $VISUAL and $EDITOR.
 
134
 
 
135
check_signatures
 
136
----------------
 
137
Defines the behavior for signatures.
 
138
 
 
139
require
 
140
    the gnupg signature for revisions must be present and must be valid
 
141
 
 
142
ignore
 
143
    Do not check gnupg signatures of revisions. 
 
144
 
 
145
check-available
 
146
    (default) If gnupg signatures for revisions are present, check them.
 
147
    Bazaar will fail if it finds a bad signature, but will not fail if
 
148
    no signature is present
 
149
 
 
150
create_signatures
 
151
-----------------
 
152
Defines the behaviour of signing revisions. Has three possible values:
 
153
always, never and when-requied.
 
154
 
 
155
always
 
156
    sign every new revision that is committed
 
157
 
 
158
when-required
 
159
    (default) Sign newly committed revisions only when the branch requires
 
160
    signed revisions
 
161
 
 
162
never
 
163
    Refuse to sign newly committed revisions, even if the branch requires signatures
 
164
 
 
165
recurse
 
166
-------
 
167
Only useful in locations.conf. Defines whether or not the configuration for
 
168
this section applies to subdirectories:
 
169
 
 
170
true
 
171
    (default) This section applies to subdirectories as well
 
172
 
 
173
false
 
174
    This section only applies to the branch at this directory and not
 
175
    branches 
 
176
 
 
177
gpg_signing_command
 
178
-------------------
 
179
(Default: "gpg"). Which program should be used to sign and check revisions.
 
180
example::
 
181
 
 
182
    gpg_signing_command = /usr/bin/gnpg
 
183