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