/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/configuration.txt

  • Committer: Brad Crittenden
  • Date: 2007-02-27 22:14:14 UTC
  • mfrom: (2293.2.2 bzr.dev)
  • mto: This revision was merged to the branch mainline in revision 2311.
  • Revision ID: bac@canonical.com-20070227221414-du51ihnpkdu59geo
Merge from my LP branch

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.  These files are sometimes referred to as ``ini files``.
 
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.  A 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
sensitive. 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.  For example::
 
51
 
 
52
    email            = John Doe <jdoe@isp.com>
 
53
    check_signatures = require
 
54
 
 
55
 
 
56
Variable 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
 
 
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.
 
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
 
76
following could be used::
 
77
 
 
78
  [/top/location]
 
79
  push_location = sftp://example.com/location
 
80
  push_location:policy = appendpath
 
81
 
 
82
With this configuration, the push location for ``/top/location/branch1``
 
83
would be ``sftp://example.com/location/branch1``.
 
84
 
 
85
 
 
86
The main configuration file, bazaar.conf
 
87
----------------------------------------
 
88
 
 
89
The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one
 
90
section called ``[DEFAULT]``. This default section contains the default
 
91
configuration options for all branches. The default section can be
 
92
overriden by providing a branch specific section in ``locations.conf``.
 
93
 
 
94
A typical ``bazaar.conf`` section often looks like the following::
 
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
 
 
102
``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for a
 
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
 
106
value for. The '?' and '*' wildcards are supported::
 
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
 
 
115
    [http://bazaar-vcs.org/bzr/*]
 
116
    check_signatures  = require
 
117
 
 
118
Common Variable Options
 
119
=======================
 
120
 
 
121
email
 
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
 
131
a commit log message. This setting is trumped by the environment variable
 
132
``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.
 
133
 
 
134
check_signatures
 
135
----------------
 
136
Defines the behavior for signatures.
 
137
 
 
138
require
 
139
    The gnupg signature for revisions must be present and must be valid.
 
140
 
 
141
ignore
 
142
    Do not check gnupg signatures of revisions. 
 
143
 
 
144
check-available
 
145
    (default) If gnupg signatures for revisions are present, check them.
 
146
    Bazaar will fail if it finds a bad signature, but will not fail if
 
147
    no signature is present.
 
148
 
 
149
create_signatures
 
150
-----------------
 
151
Defines the behaviour of signing revisions.
 
152
 
 
153
always
 
154
    Sign every new revision that is committed.
 
155
 
 
156
when-required
 
157
    (default) Sign newly committed revisions only when the branch requires
 
158
    signed revisions.
 
159
 
 
160
never
 
161
    Refuse to sign newly committed revisions, even if the branch requires signatures.
 
162
 
 
163
recurse
 
164
-------
 
165
Only useful in ``locations.conf``. Defines whether or not the configuration for
 
166
this section applies to subdirectories:
 
167
 
 
168
true
 
169
    (default) This section applies to subdirectories.
 
170
 
 
171
false
 
172
    This section only applies to the branch at this directory and not
 
173
    branches below it. 
 
174
 
 
175
gpg_signing_command
 
176
-------------------
 
177
(Default: "gpg"). Which program should be used to sign and check revisions.
 
178
For example::
 
179
 
 
180
    gpg_signing_command = /usr/bin/gnpg
 
181
 
 
182
 
 
183
Branch 6 Options
 
184
================
 
185
 
 
186
These options apply only to branches that use the "experimental-branch6"
 
187
format.  They are usually set in ``.bzr/branch/branch.conf`` automatically, but
 
188
may be manually set in ``locations.conf`` or ``bazaar.conf``.
 
189
 
 
190
append_revisions_only
 
191
---------------------
 
192
If set to "true" then revisions can only be appended to the log, not
 
193
removed.  A branch with this setting enabled can only pull from
 
194
another branch if the other branch's log is a longer version of its
 
195
own.  This is normally set by ``bzr init --append-revisions-only``.
 
196
 
 
197
parent_location
 
198
---------------
 
199
If present, the location of the default branch for pull or merge.
 
200
This option is normally set by ``pull --remember`` or ``merge
 
201
--remember``
 
202
 
 
203
push_location
 
204
-------------
 
205
If present, the location of the default branch for push.  This option
 
206
is normally set by ``push --remember``.
 
207
 
 
208
bound_location
 
209
--------------
 
210
The location that commits should go to when acting as a checkout.
 
211
This option is normally set by ``bind``.
 
212
 
 
213
bound
 
214
-----
 
215
If set to "True", the branch should act as a checkout, and push each commit to
 
216
the bound_location.  This option is normally set by ``bind``/``unbind``.