/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/en/user-guide/configuring_breezy.txt

  • Committer: Jelmer Vernooij
  • Date: 2018-07-08 14:45:27 UTC
  • mto: This revision was merged to the branch mainline in revision 7036.
  • Revision ID: jelmer@jelmer.uk-20180708144527-codhlvdcdg9y0nji
Fix a bunch of merge tests.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/configuring_breezy.txt
1
 
Configuring Bazaar
 
1
Configuring Breezy
2
2
==================
3
3
 
4
 
Telling Bazaar about yourself
 
4
Telling Breezy about yourself
5
5
-----------------------------
6
6
 
7
7
One function of a version control system is to keep track of who changed
8
8
what.  In a decentralized system, that requires an identifier for each
9
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
 
10
email address. Breezy is smart enough to automatically generate an email
11
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
 
12
guess that Breezy makes, then use the ``whoami`` command to set the
13
13
identifier you want::
14
14
 
15
 
    % bzr whoami "Your Name <email@example.com>"
 
15
    % brz 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 Breezy, 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, Breezy 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
 
19
59
Configuration files
20
60
-------------------
21
61
 
22
 
Configuration files are located in ``$HOME/.bazaar`` on Linux/Unix and
23
 
``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on
 
62
Configuration files are located in ``$HOME/.config/breezy`` on Unix and
 
63
``C:\Documents and Settings\<username>\Application Data\Breezy\2.0`` on
24
64
Windows. There are three primary configuration files in this location:
25
65
 
26
 
* ``bazaar.conf`` describes default configuration options,
 
66
* ``breezy.conf`` describes default configuration options,
27
67
 
28
68
* ``locations.conf`` describes configuration information for
29
69
  specific branch locations,
32
72
  remote servers.
33
73
 
34
74
Each branch can also contain a configuration file that sets values specific
35
 
to that branch. This file is found at ``.bzr/branch/branch.conf`` within the
 
75
to that branch. This file is found at ``.brz/branch/branch.conf`` within the
36
76
branch. This file is visible to **all users of a branch**. If you wish to
37
77
override one of the values for a branch with a setting that is specific to you,
38
78
then you can do so in ``locations.conf``.
39
79
 
40
 
Here is sample content of ``bazaar.conf`` after setting an email address using
 
80
Here is sample content of ``breezy.conf`` after setting an email address using
41
81
the ``whoami`` command::
42
82
 
43
83
  [DEFAULT]
44
84
  email = Your Name <email@example.com>
45
85
 
46
86
For further details on the syntax and configuration settings supported, see
47
 
`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_
48
 
in the Bazaar User Reference.
 
87
`Configuration Settings <../user-reference/index.html#configuration-settings>`_
 
88
in the Breezy User Reference.
 
89
 
 
90
 
 
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
  brz config
 
98
 
 
99
``brz`` 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
  * ``breezy.conf`` is searched next,
 
111
 
 
112
  * finally, some options can have default values generally defined in the
 
113
    code itself and not displayed by ``brz config`` (see `Configuration
 
114
    Settings <../user-reference/index.html#configuration-settings>`_).
 
115
 
 
116
This is better understood by using ```brz 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/brz/
 
124
    nickname = config-modify
 
125
    push_location = bzr+ssh://bazaar.launchpad.net/~vila/brz/config-modify/
 
126
  breezy:
 
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
  brz 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
  brz config opt=value
 
145
 
 
146
An option value can reference another option by enclosing it in curly
 
147
braces::
 
148
 
 
149
  brz config opt={other_opt}/subdir
 
150
 
 
151
If ``other_opt`` is set to ``'root``, ``brz 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
  brz config --all .*opt
 
159
 
 
160
  breezy:
 
161
    [DEFAULT]
 
162
    opt = {other_opt}/subdir
 
163
    other_opt = root
 
164
 
 
165
 
 
166
 
 
167
 
 
168
 
 
169
To remove an option use::
 
170
 
 
171
  brz config --remove opt
49
172
 
50
173
 
51
174
Rule-based preferences
56
179
``BZR_HOME/rules``.
57
180
 
58
181
For further information on how rules are searched and the detailed syntax of
59
 
the relevant files, see `Rules <../user-reference/bzr_man.html#rules>`_
60
 
in the Bazaar User Reference.
 
182
the relevant files, see `Rules <../user-reference/index.html#rules>`_
 
183
in the Breezy 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"