~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/configuring_bazaar.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2008-09-03 22:30:56 UTC
  • mfrom: (3644.2.13 index_builder_cleanup)
  • Revision ID: pqm@pqm.ubuntu.com-20080903223056-b108iytb38xkznci
(jam) Streamline BTreeBuilder.add_node et al to make btree creation
        faster.

Show diffs side-by-side

added added

removed removed

Lines of Context:
13
13
identifier you want::
14
14
 
15
15
    % bzr whoami "Your Name <email@example.com>"
16
 
 
 
16
 
17
17
If ``whoami`` is used without an argument, the current value is displayed.
18
18
 
19
 
Using a network proxy
20
 
---------------------
21
 
 
22
 
If your network requires that you use an HTTP proxy for outbound
23
 
connections, you must set the ``http_proxy`` variable.  If the proxy is
24
 
also required for https connections, you need to set ``https_proxy`` too.
25
 
If you need these and don't have them set, you may find that connections
26
 
to Launchpad or other external servers fail or time out.
27
 
 
28
 
On Unix you typically want to set these in ``/etc/environment`` or
29
 
``~/.bash_profile`` and on Windows in the user profile.
30
 
 
31
 
::
32
 
 
33
 
  http_proxy=http://proxy.example.com:3128/
34
 
  https_proxy=http://proxy.example.com:3128/
35
 
 
36
 
The ``no_proxy`` variable can be set to a comma-separated list of hosts
37
 
which shouldn't be reached by the proxy.  (See
38
 
<http://docs.python.org/library/urllib.html> for more details.)
39
 
 
40
 
Various ways to configure
41
 
-------------------------
42
 
 
43
 
As shown in the example above, there are various ways to
44
 
configure Bazaar, they all share some common properties though.
45
 
An option has:
46
 
 
47
 
- a name which is generally a valid python identifier,
48
 
 
49
 
- a value which is a string. In some cases, Bazaar will be able
50
 
  to recognize special values like 'True', 'False' to infer a
51
 
  boolean type, but basically, as a user, you will always specify
52
 
  a value as a string.
53
 
 
54
 
Options are grouped in various contexts so the option name
55
 
uniquely identifies it in this context. When needed, options can
56
 
be made persistent by recording them in a configuration file.
57
 
 
58
 
 
59
19
Configuration files
60
20
-------------------
61
21
 
62
 
Configuration files are located in ``$HOME/.bazaar`` on Unix and
 
22
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
63
23
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
64
24
Windows. There are three primary configuration files in this location:
65
25
 
84
44
  email = Your Name <email@example.com>
85
45
 
86
46
For further details on the syntax and configuration settings supported, see
87
 
`Configuration Settings <../user-reference/index.html#configuration-settings>`_
 
47
`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_
88
48
in the Bazaar User Reference.
89
49
 
90
50
 
91
 
Looking at the active configuration
92
 
-----------------------------------
93
 
 
94
 
To look at all the currently defined options, you can use the following
95
 
command::
96
 
 
97
 
  bzr config
98
 
 
99
 
``bzr`` implements some rules to decide where to get the value of a
100
 
configuration option.
101
 
 
102
 
The current policy is to examine the existing configurations files in a
103
 
given order for matching definitions.
104
 
 
105
 
  * ``locations.conf`` is searched first for a section whose name matches the
106
 
    location considered (working tree, branch or remote branch),
107
 
 
108
 
  * the current ``branch.conf`` is searched next,
109
 
 
110
 
  * ``bazaar.conf`` is searched next,
111
 
 
112
 
  * finally, some options can have default values generally defined in the
113
 
    code itself and not displayed by ``bzr config`` (see `Configuration
114
 
    Settings <../user-reference/index.html#configuration-settings>`_).
115
 
 
116
 
This is better understood by using ```bzr config`` with no arguments, which
117
 
will display some output of the form::
118
 
 
119
 
  locations:
120
 
    post_commit_to = commits@example.com
121
 
    news_merge_files = NEWS
122
 
  branch:
123
 
    parent_location = bzr+ssh://bazaar.launchpad.net/+branch/bzr/
124
 
    nickname = config-modify
125
 
    push_location = bzr+ssh://bazaar.launchpad.net/~vila/bzr/config-modify/
126
 
  bazaar:
127
 
    debug_flags = hpss,
128
 
 
129
 
Each configuration file is associated with a given scope whose name is
130
 
displayed before each set of defined options.
131
 
 
132
 
If you need to look at a specific option, you can use::
133
 
 
134
 
  bzr config <option>
135
 
 
136
 
This will display only the option value and is intended to be used in
137
 
scripts.
138
 
 
139
 
Modifying the active configuration
140
 
----------------------------------
141
 
 
142
 
To set an option to a given value use::
143
 
 
144
 
  bzr config opt=value
145
 
 
146
 
An option value can reference another option by enclosing it in curly
147
 
braces::
148
 
 
149
 
  bzr config opt={other_opt}/subdir
150
 
 
151
 
If ``other_opt`` is set to ``'root``, ``bzr config opt`` will display::
152
 
 
153
 
  root/subdir
154
 
 
155
 
Note that when ``--all`` is used, the references are left as-is to better
156
 
reflect the content of the config files and make it easier to organize them::
157
 
 
158
 
  bzr config --all .*opt
159
 
 
160
 
  bazaar:
161
 
    [DEFAULT]
162
 
    opt = {other_opt}/subdir
163
 
    other_opt = root
164
 
 
165
 
 
166
 
 
167
 
 
168
 
 
169
 
To remove an option use::
170
 
 
171
 
  bzr config --remove opt
172
 
 
173
 
 
174
51
Rule-based preferences
175
52
----------------------
176
53
 
179
56
``BZR_HOME/rules``.
180
57
 
181
58
For further information on how rules are searched and the detailed syntax of
182
 
the relevant files, see `Rules <../user-reference/index.html#rules>`_
 
59
the relevant files, see `Rules <../user-reference/bzr_man.html#rules>`_
183
60
in the Bazaar User Reference.
184
 
 
185
 
 
186
 
Escaping command lines
187
 
----------------------
188
 
 
189
 
When you give a program name or command line in configuration, you can quote
190
 
to include special characters or whitespace.  The same rules are used across
191
 
all platforms.
192
 
 
193
 
The rules are: strings surrounded by double-quotes are interpreted as single
194
 
"words" even if they contain whitespace, and backslash may be used to quote
195
 
quotation marks.  For example::
196
 
 
197
 
    BZR_EDITOR="C:\Program Files\My Editor\myeditor.exe"