← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/configuration.txt

  • Committer: Robert Collins
  • Date: 2005-10-11 07:00:25 UTC
  • mto: This revision was merged to the branch mainline in revision 1443.
  • Revision ID: robertc@robertcollins.net-20051011070025-bac6b53cb6186dfd
create a config module - there is enough config logic to make this worthwhile, and start testing config processing.

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, locations.conf, contains configuration information for specific
6
 
branch locations.
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 locations.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 locations.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/locations.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 locations.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