~bzr-pqm/bzr/bzr.dev

====================
Bazaar configuration
====================

Information on how to configure Bazaar.

Location of configuration file
==============================
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``.

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


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


Bug Tracker Options
===================

These options can go into bazaar.conf, branch.conf or into a branch-specific
configuration section in locations.conf.

bugzilla_<tracker_abbreviation>_url
-----------------------------------
If present, the location of the Bugzilla bug tracker referred to by
<tracker_abbreviation>. This option can then be used together with ``bzr commit
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
example::

    bugzilla_squid_url = http://www.squid-cache.org/bugs

would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
fixed.

trac_<tracker_abbrevation>_url
------------------------------
If present, the location of the Trac instance referred to by
<tracker_abbreviation>. This option can then be used together with ``bzr commit
--fixes`` to mark bugs in that tracker as being fixed by that commit. For
example::

    trac_twisted_url = http://www.twistedmatrix.com/trac

would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
fixed.