← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Aaron Bentley
  • Date: 2005-08-26 14:39:43 UTC
  • mfrom: (974.2.7) (974.2.6)
  • mto: (1185.3.4)
  • mto: This revision was merged to the branch mainline in revision 1178.
  • Revision ID: abentley@panoramicfeedback.com-20050826143943-c677569cfb887d35
Merged changes from the merge4 branch

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/configuring_bazaar.txt
1
 
Configuring Bazaar
2
 
==================
3
 
 
4
 
Telling Bazaar about yourself
5
 
-----------------------------
6
 
 
7
 
One function of a version control system is to keep track of who changed
8
 
what.  In a decentralized system, that requires an identifier for each
9
 
author that is globally unique.  Most people already have one of these: an
10
 
email address. Bazaar is smart enough to automatically generate an email
11
 
address by looking up your username and hostname. If you don't like the
12
 
guess that Bazaar makes, then use the ``whoami`` command to set the
13
 
identifier you want::
14
 
 
15
 
    % bzr whoami "Your Name <email@example.com>"
16
 
 
17
 
If ``whoami`` is used without an argument, the current value is displayed.
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
 
 
41
 
Configuration files
42
 
-------------------
43
 
 
44
 
Configuration files are located in ``$HOME/.bazaar`` on Unix and
45
 
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
46
 
Windows. There are three primary configuration files in this location:
47
 
 
48
 
* ``bazaar.conf`` describes default configuration options,
49
 
 
50
 
* ``locations.conf`` describes configuration information for
51
 
  specific branch locations,
52
 
 
53
 
* ``authentication.conf`` describes credential information for
54
 
  remote servers.
55
 
 
56
 
Each branch can also contain a configuration file that sets values specific
57
 
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
58
 
branch. This file is visible to **all users of a branch**. If you wish to
59
 
override one of the values for a branch with a setting that is specific to you,
60
 
then you can do so in ``locations.conf``.
61
 
 
62
 
Here is sample content of ``bazaar.conf`` after setting an email address using
63
 
the ``whoami`` command::
64
 
 
65
 
  [DEFAULT]
66
 
  email = Your Name <email@example.com>
67
 
 
68
 
For further details on the syntax and configuration settings supported, see
69
 
`Configuration Settings <../user-reference/index.html#configuration-settings>`_
70
 
in the Bazaar User Reference.
71
 
 
72
 
 
73
 
Looking at the active configuration
74
 
-----------------------------------
75
 
 
76
 
To look at all the currently defined options, you can use the following
77
 
command::
78
 
 
79
 
  bzr config
80
 
 
81
 
``bzr`` implements some rules to decide where to get the value of a
82
 
configuration option.
83
 
 
84
 
The current policy is to examine the existing configurations files in a
85
 
given order for matching definitions.
86
 
 
87
 
  * ``locations.conf`` is searched first for a section whose name matches the
88
 
    location considered (working tree, branch or remote branch),
89
 
 
90
 
  * the current ``branch.conf`` is searched next,
91
 
 
92
 
  * ``bazaar.conf`` is searched next,
93
 
 
94
 
  * finally, some options can have default values generally defined in the
95
 
    code itself and not displayed by ``bzr config`` (see `Configuration
96
 
    Settings <../user-reference/index.html#configuration-settings>`_).
97
 
 
98
 
This is better understood by using ```bzr config`` with no arguments, which
99
 
will display some output of the form::
100
 
 
101
 
  locations:
102
 
    post_commit_to = commits@example.com
103
 
    news_merge_files = NEWS
104
 
  branch:
105
 
    parent_location = bzr+ssh://bazaar.launchpad.net/+branch/bzr/
106
 
    nickname = config-modify
107
 
    push_location = bzr+ssh://bazaar.launchpad.net/~vila/bzr/config-modify/
108
 
  bazaar:
109
 
    debug_flags = hpss,
110
 
 
111
 
Each configuration file is associated with a given scope whose name is
112
 
displayed before each set of defined options.
113
 
 
114
 
Modifying the active configuration
115
 
----------------------------------
116
 
 
117
 
To set an option to a given value use::
118
 
 
119
 
  bzr config opt=value
120
 
 
121
 
To remove an option use::
122
 
 
123
 
  bzr config --remove opt
124
 
 
125
 
 
126
 
Rule-based preferences
127
 
----------------------
128
 
 
129
 
Some commands and plugins provide custom processing on files matching
130
 
certain patterns. Per-user rule-based preferences are defined in
131
 
``BZR_HOME/rules``.
132
 
 
133
 
For further information on how rules are searched and the detailed syntax of
134
 
the relevant files, see `Rules <../user-reference/index.html#rules>`_
135
 
in the Bazaar User Reference.
136
 
 
137
 
 
138
 
Escaping command lines
139
 
----------------------
140
 
 
141
 
When you give a program name or command line in configuration, you can quote
142
 
to include special characters or whitespace.  The same rules are used across
143
 
all platforms.
144
 
 
145
 
The rules are: strings surrounded by double-quotes are interpreted as single
146
 
"words" even if they contain whitespace, and backslash may be used to quote
147
 
quotation marks.  For example::
148
 
 
149
 
    BZR_EDITOR="C:\Program Files\My Editor\myeditor.exe"