/brz/remove-bazaar

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

Bazaar configuration

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

Information on how to configure Bazaar.

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

.. branch.conf.

Environment variables

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

While most configuration is handled by configuration files, some options

which may be semi-permanent can also be controlled through the environment.

BZR_EMAIL

---------

Override the email id used by Bazaar.  Typical format::

  "John Doe <jdoe@example.com>"

See also the ``email`` configuration value.

BZR_PROGRESS_BAR

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

Override the progress display.  Possible values are "none", "dots", "tty"

BZR_SIGQUIT_PDB

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

Control whether SIGQUIT behaves normally or invokes a breakin debugger.

0 = Standard SIGQUIT behavior

1 = Invoke breakin debugger (default)

BZR_HOME

--------

Override the home directory used by Bazaar.

BZR_SSH

-------

Select a different SSH implementation.

BZR_PDB

-------

Control whether to launch a debugger on error.

0 = Standard behavior

1 = Launch debugger

BZR_REMOTE_PATH

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

Path to the Bazaar executable to use when using the bzr+ssh protocol.

See also the ``bzr_remote_path`` configuration value

BZR_EDITOR

----------

Path to the editor Bazaar should use for commit messages, etc.

BZR_PLUGIN_PATH

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

The path to the plugins directory that Bazaar should use.

BZRPATH

-------

The path where Bazaar should look for shell plugin external commands.

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

bzr_remote_path

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

(Default: "bzr").  The path to the command that should be used to run the smart

server for bzr.  This value may only be specified in locations.conf, because:

- it's needed before branch.conf is accessible

- allowing remote branch.conf files to specify commands would be a security

  risk

It is overridden by the BZR_REMOTE_PATH environment variable.

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.

mail_client

-----------

A mail client to use for sending merge requests.

By default, bzr will try to use ``mapi`` on Windows.  On other platforms, it

will try ``xdg-email``. If either of these fails, it will fall back to

``editor``.

Supported values for specific clients:

:evolution: Use Evolution.

:kmail: Use KMail.

:mutt: Use Mutt.

:thunderbird: Use Mozilla Thunderbird or Icedove.  For Thunderbird/Icedove 1.5,

    this works around some bugs that xdg-email doesn't handle.

Supported generic values are:

:default: See above.

:editor: Use your editor to compose the merge request.  This also uses

    your commit id, (see ``bzr whoami``), smtp_server and (optionally)

    smtp_username and smtp_password.

:mapi: Use your preferred e-mail client on Windows.

:xdg-email: Use xdg-email to run your preferred mail program

submit_branch

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

The branch you intend to submit your current work to.  This is automatically

set by ``bzr send``, and is also used by the ``submit:`` revision spec.  This

should usually be set on a per-branch or per-location basis.

public_branch

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

A publically-accessible version of this branch (implying that this version is

not publically-accessible).  Used (and set) by ``bzr send``.

Branch 6 Options

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

These options apply only to branches that use the "dirstate-tags" 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``.