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