~bzr-pqm/bzr/bzr.dev

Configuring Bazaar

==================

Telling Bazaar about yourself

-----------------------------

One function of a version control system is to keep track of who changed

what.  In a decentralized system, that requires an identifier for each

author that is globally unique.  Most people already have one of these: an

email address. Bazaar is smart enough to automatically generate an email

address by looking up your username and hostname. If you don't like the

guess that Bazaar makes, then use the ``whoami`` command to set the

identifier you want::

    % bzr whoami "Your Name <email@example.com>"

If ``whoami`` is used without an argument, the current value is displayed.

Using a network proxy

---------------------

If your network requires that you use an HTTP proxy for outbound

connections, you must set the ``http_proxy`` variable.  If the proxy is

also required for https connections, you need to set ``https_proxy`` too.

If you need these and don't have them set, you may find that connections

to Launchpad or other external servers fail or time out.

On Unix you typically want to set these in ``/etc/environment`` or

``~/.bash_profile`` and on Windows in the user profile.

::

  http_proxy=http://proxy.example.com:3128/

  https_proxy=http://proxy.example.com:3128/

The ``no_proxy`` variable can be set to a comma-separated list of hosts

which shouldn't be reached by the proxy.  (See

<http://docs.python.org/library/urllib.html> for more details.)

Various ways to configure

-------------------------

As shown in the example above, there are various ways to

configure Bazaar, they all share some common properties though.

An option has:

- a name which is generally a valid python identifier,

- a value which is a string. In some cases, Bazaar will be able

  to recognize special values like 'True', 'False' to infer a

  boolean type, but basically, as a user, you will always specify

  a value as a string.

Options are grouped in various contexts so the option name

uniquely identifies it in this context. When needed, options can

be made persistent by recording them in a configuration file.

Configuration files

-------------------

Configuration files are located in ``$HOME/.bazaar`` on Unix and

``C:\Documents and Settings\<username>\Application Data\Bazaar\2.0`` on

Windows. There are three primary configuration files in this location:

* ``bazaar.conf`` describes default configuration options,

* ``locations.conf`` describes configuration information for

  specific branch locations,

* ``authentication.conf`` describes credential information for

  remote servers.

Each branch can also contain a configuration file that sets values specific

to that branch. This file is found at ``.bzr/branch/branch.conf`` within the

branch. This file is visible to **all users of a branch**. If you wish to

override one of the values for a branch with a setting that is specific to you,

then you can do so in ``locations.conf``.

Here is sample content of ``bazaar.conf`` after setting an email address using

the ``whoami`` command::

  [DEFAULT]

  email = Your Name <email@example.com>

For further details on the syntax and configuration settings supported, see

`Configuration Settings <../user-reference/index.html#configuration-settings>`_

in the Bazaar User Reference.

Looking at the active configuration

-----------------------------------

To look at all the currently defined options, you can use the following

command::

  bzr config

``bzr`` implements some rules to decide where to get the value of a

configuration option.

The current policy is to examine the existing configurations files in a

given order for matching definitions.

  * ``locations.conf`` is searched first for a section whose name matches the

    location considered (working tree, branch or remote branch),

  * the current ``branch.conf`` is searched next,

  * ``bazaar.conf`` is searched next,

  * finally, some options can have default values generally defined in the

    code itself and not displayed by ``bzr config`` (see `Configuration

    Settings <../user-reference/index.html#configuration-settings>`_).

This is better understood by using ```bzr config`` with no arguments, which

will display some output of the form::

  locations:

    post_commit_to = commits@example.com

    news_merge_files = NEWS

  branch:

    parent_location = bzr+ssh://bazaar.launchpad.net/+branch/bzr/

    nickname = config-modify

    push_location = bzr+ssh://bazaar.launchpad.net/~vila/bzr/config-modify/

  bazaar:

    debug_flags = hpss,

Each configuration file is associated with a given scope whose name is

displayed before each set of defined options.

If you need to look at a specific option, you can use::

  bzr config <option>

This will display only the option value and is intended to be used in

scripts.

Modifying the active configuration

----------------------------------

To set an option to a given value use::

  bzr config opt=value

An option value can reference another option by enclosing it in curly

braces::

  bzr config opt={other_opt}/subdir

If ``other_opt`` is set to ``'root``, ``bzr config opt`` will display::

  root/subdir

Note that when ``--all`` is used, the references are left as-is to better

reflect the content of the config files and make it easier to organize them::

  bzr config --all .*opt

  bazaar:

    [DEFAULT]

    opt = {other_opt}/subdir

    other_opt = root

To remove an option use::

  bzr config --remove opt

Rule-based preferences

----------------------

Some commands and plugins provide custom processing on files matching

certain patterns. Per-user rule-based preferences are defined in

``BZR_HOME/rules``.

For further information on how rules are searched and the detailed syntax of

the relevant files, see `Rules <../user-reference/index.html#rules>`_

in the Bazaar User Reference.

Escaping command lines

----------------------

When you give a program name or command line in configuration, you can quote

to include special characters or whitespace.  The same rules are used across

all platforms.

The rules are: strings surrounded by double-quotes are interpreted as single

"words" even if they contain whitespace, and backslash may be used to quote

quotation marks.  For example::

    BZR_EDITOR="C:\Program Files\My Editor\myeditor.exe"