~bzr-pqm/bzr/bzr.dev

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

Bazaar configuration

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

Information on how to configure Bazaar.

.. TODO: Should have some explanation of why you'd want things in

.. branch.conf.

Location of configuration files

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

Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first

one, named ``bazaar.conf``, includes default configuration options. The other

file, ``locations.conf``, contains configuration information for specific

branch locations.  These files are sometimes referred to as ``ini files``.

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``.

General Format

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

An ini file has three types of contructs: section headers, section

variables and comments.

Comments

--------

A comment is any line that starts with a "#" (sometimes called a "hash

mark", "pound sign" or "number sign"). Comment lines are ignored by

Bazaar when parsing ini files.

Section Headers

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

A section header is a word enclosed in brackets that starts at the begining

of a line.  A typical section header looks like this::

    [DEFAULT]

The only valid section header for bazaar.conf is [DEFAULT], which is

case sensitive. The default section provides for setting variables

which can be overridden with the branch config file.

For ``locations.conf``, the variables from the section with the

longest matching section header are used to the exclusion of other

potentially valid section headers. A section header uses the path for

the branch as the section header. Some examples include::

    [http://mybranches.isp.com/~jdoe/branchdir]

    [/home/jdoe/branches/]

Section Variables

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

A section variable resides within a section. A section variable contains a

variable name, an equals sign and a value.  For example::

    email            = John Doe <jdoe@isp.com>

    check_signatures = require

Variable Policies

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

Variables defined in a section affect the named directory or URL plus

any locations they contain.  Policies can be used to change how a

variable value is interpreted for contained locations.  Currently

there are three policies available:

 none:

   the value is interpreted the same for contained locations.  This is

   the default behaviour.

 norecurse:

   the value is only used for the exact location specified by the

   section name.

 appendpath:

   for contained locations, any additional path components are

   appended to the value.

Policies are specified by keys with names of the form "$var:policy".

For example, to define the push location for a tree of branches, the

following could be used::

  [/top/location]

  push_location = sftp://example.com/location

  push_location:policy = appendpath

With this configuration, the push location for ``/top/location/branch1``

would be ``sftp://example.com/location/branch1``.

The main configuration file, bazaar.conf

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

The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one

section called ``[DEFAULT]``. This default section contains the default

configuration options for all branches. The default section can be

overriden by providing a branch-specific section in ``locations.conf``.

A typical ``bazaar.conf`` section often looks like the following::

    [DEFAULT]

    email             = John Doe <jdoe@isp.com>

    editor            = /usr/bin/vim

    check_signatures  = check-available

    create_signatures = when-required

``$HOME/.bazaar/locations.conf`` allows one to specify overriding settings for a

specific branch. The format is almost identical to the default section in

bazaar.conf with one significant change: The section header, instead of

saying default, will be the path to a branch that you wish to override a

value for. The '?' and '*' wildcards are supported::

    [/home/jdoe/branches/nethack]

    email = Nethack Admin <nethack@nethack.com>

    [http://hypothetical.site.com/branches/devel-branch]

    create_signatures = always

    check_signatures  = always

    [http://bazaar-vcs.org/bzr/*]

    check_signatures  = require

Common Variable Options

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

email

-----

The email address to use when committing a branch. Typically takes the form

of::

    email = Full Name <account@hostname.tld>

editor

------

The path of the editor that you wish to use if *bzr commit* is run without

a commit message. This setting is trumped by the environment variable

``$BZR_EDITOR``, and overrides ``$VISUAL`` and ``$EDITOR``.

check_signatures

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

Defines the behavior for signatures.

require

    The gnupg signature for revisions must be present and must be valid.

ignore

    Do not check gnupg signatures of revisions.

check-available

    (default) If gnupg signatures for revisions are present, check them.

    Bazaar will fail if it finds a bad signature, but will not fail if

    no signature is present.

create_signatures

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

Defines the behaviour of signing revisions.

always

    Sign every new revision that is committed.

when-required

    (default) Sign newly committed revisions only when the branch requires

    signed revisions.

never

    Refuse to sign newly committed revisions, even if the branch

    requires signatures.

recurse

-------

Only useful in ``locations.conf``. Defines whether or not the

configuration for this section applies to subdirectories:

true

    (default) This section applies to subdirectories as well.

false

    This section only applies to the branch at this directory and not

    branches below it.

gpg_signing_command

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

(Default: "gpg"). Which program should be used to sign and check revisions.

For example::

    gpg_signing_command = /usr/bin/gnpg

smtp_server

-----------

(Default: "localhost"). SMTP server to use when Bazaar needs to send

email, eg. with ``merge-directive --mail-to``, or the bzr-email plugin.

smtp_username, smtp_password

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

User and password to authenticate to the SMTP server. If smtp_username

is set, and smtp_password is not, Bazaar will prompt for a password.

These settings are only needed if the SMTP server requires authentication

to send mail.

Branch 6 Options

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

These options apply only to branches that use the "experimental-branch6"

format.  They are usually set in ``.bzr/branch/branch.conf`` automatically, but

may be manually set in ``locations.conf`` or ``bazaar.conf``.

append_revisions_only

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

If set to "True" then revisions can only be appended to the log, not

removed.  A branch with this setting enabled can only pull from

another branch if the other branch's log is a longer version of its

own.  This is normally set by ``bzr init --append-revisions-only``.

parent_location

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

If present, the location of the default branch for pull or merge.

This option is normally set by ``pull --remember`` or ``merge

--remember``.

push_location

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

If present, the location of the default branch for push.  This option

is normally set by ``push --remember``.

bound_location

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

The location that commits should go to when acting as a checkout.

This option is normally set by ``bind``.

bound

-----

If set to "True", the branch should act as a checkout, and push each commit to

the bound_location.  This option is normally set by ``bind``/``unbind``.