Bazaar User Reference

Version: 1.17rc1
Generated:2009-07-14

Contents


About This Manual

This manual is generated from Bazaar's online help. To use the online help system, try the following commands.

Introduction including a list of commonly used commands:

bzr help

List of topics and a summary of each:

bzr help topics

List of commands and a summary of each:

bzr help commands

More information about a particular topic or command:

bzr help topic-or-command-name

The following web sites provide further information on Bazaar:

Home page:http://www.bazaar-vcs.org/
Official docs:http://doc.bazaar-vcs.org/
Launchpad:https://launchpad.net/bzr/

Concepts

Branches

A branch consists of the state of a project, including all of its history. All branches have a repository associated (which is where the branch history is stored), but multiple branches may share the same repository (a shared repository). Branches can be copied and merged.

Related commands:

init    Change a directory into a versioned branch.
branch  Create a new branch that is a copy of an existing branch.
merge   Perform a three-way merge.

Checkouts

Checkouts are source trees that are connected to a branch, so that when you commit in the source tree, the commit goes into that branch. They allow you to use a simpler, more centralized workflow, ignoring some of Bazaar's decentralized features until you want them. Using checkouts with shared repositories is very similar to working with SVN or CVS, but doesn't have the same restrictions. And using checkouts still allows others working on the project to use whatever workflow they like.

A checkout is created with the bzr checkout command (see "help checkout"). You pass it a reference to another branch, and it will create a local copy for you that still contains a reference to the branch you created the checkout from (the master branch). Then if you make any commits they will be made on the other branch first. This creates an instant mirror of your work, or facilitates lockstep development, where each developer is working together, continuously integrating the changes of others.

However the checkout is still a first class branch in Bazaar terms, so that you have the full history locally. As you have a first class branch you can also commit locally if you want, for instance due to the temporary loss af a network connection. Use the --local option to commit to do this. All the local commits will then be made on the master branch the next time you do a non-local commit.

If you are using a checkout from a shared branch you will periodically want to pull in all the changes made by others. This is done using the "update" command. The changes need to be applied before any non-local commit, but Bazaar will tell you if there are any changes and suggest that you use this command when needed.

It is also possible to create a "lightweight" checkout by passing the --lightweight flag to checkout. A lightweight checkout is even closer to an SVN checkout in that it is not a first class branch, it mainly consists of the working tree. This means that any history operations must query the master branch, which could be slow if a network connection is involved. Also, as you don't have a local branch, then you cannot commit locally.

Lightweight checkouts work best when you have fast reliable access to the master branch. This means that if the master branch is on the same disk or LAN a lightweight checkout will be faster than a heavyweight one for any commands that modify the revision history (as only one copy of the branch needs to be updated). Heavyweight checkouts will generally be faster for any command that uses the history but does not change it, but if the master branch is on the same disk then there won't be a noticeable difference.

Another possible use for a checkout is to use it with a treeless repository containing your branches, where you maintain only one working tree by switching the master branch that the checkout points to when you want to work on a different branch.

Obviously to commit on a checkout you need to be able to write to the master branch. This means that the master branch must be accessible over a writeable protocol , such as sftp://, and that you have write permissions at the other end. Checkouts also work on the local file system, so that all that matters is file permissions.

You can change the master of a checkout by using the "bind" command (see "help bind"). This will change the location that the commits are sent to. The bind command can also be used to turn a branch into a heavy checkout. If you would like to convert your heavy checkout into a normal branch so that every commit is local, you can use the "unbind" command.

Related commands:

checkout    Create a checkout. Pass --lightweight to get a lightweight
            checkout
update      Pull any changes in the master branch in to your checkout
commit      Make a commit that is sent to the master branch. If you have
            a heavy checkout then the --local option will commit to the
            checkout without sending the commit to the master
bind        Change the master branch that the commits in the checkout will
            be sent to
unbind      Turn a heavy checkout into a standalone branch so that any
            commits are only made locally

Content Filters

Content formats

Bazaar's content filtering allows you to store files in a different format from the copy in your working tree. This lets you, or your co-developers, use Windows development tools that expect CRLF files on projects that use other line-ending conventions. Among other things, content filters also let Linux developers more easily work on projects using Windows line-ending conventions, keyword expansion/compression, and trailing spaces on lines in text files to be implicitly stripped when committed.

To generalize, there are two content formats supported by Bazaar:

  • a canonical format - how files are stored internally
  • a convenience format - how files are created in a working tree.

Format conversion

The conversion between these formats is done by content filters. A content filter has two parts:

  • a read converter - converts from convenience to canonical format
  • a write converter - converts from canonical to convenience format.

Many of these converters will provide round-trip conversion, i.e. applying the read converter followed by the write converter gives back the original content. However, others may provide an asymmetric conversion. For example, a read converter might strip trailing whitespace off lines in source code while the matching write converter might pass content through unchanged.

Enabling content filters

Content filters are typically provided by plugins, so the first step in using them is to install the relevant plugins and read their documentation. Some plugins may be very specific about which files they filter, e.g. only files ending in .java or .php. In other cases, the plugin may leave it in the user's hands to define which files are to be filtered. This is typically done using rule-based preferences. See bzr help rules for general information about defining these.

Impact on commands

Read converters are only applied to commands that read content from a working tree, e.g. status, diff and commit. For example, bzr diff will apply read converters to files in the working tree, then compare the results to the content last committed.

Write converters are only applied by commands that create files in a working tree, e.g. branch, checkout, update. If you wish to see the canonical format of a file or tree, use bzr cat or bzr export respectively.

Note: bzr commit does not implicitly apply write converters after comitting files. If this makes sense for a given plugin providing a content filter, the plugin can usually achieve this effect by using a start_commit or post_commit hook say. See bzr help hooks and Using hooks in the Bazaar User Guide for more information on hooks.

Refreshing your working tree

For performance reasons, Bazaar caches the timestamps of files in a working tree, and assumes files are unchanged if their timestamps match the cached values. As a consequence, there are times when you may need to explicitly ask for content filtering to be reapplied in one or both directions, e.g. after installing or reconfiguring plugins providing it.

Here are some general guidelines for doing this:

  • To reapply read converters, touch files, i.e. update their timestamp. Operations like bzr status should then reapply the relevant read converters and compare the end result with the canonical format.
  • To reapply write converters, ensure there are no local changes, delete the relevant files and run bzr revert on those files.

Note: In the future, it is likely that additional options will be added to commands to make this refreshing process faster and safer.

Criss-Cross

A criss-cross in the branch history can cause the default merge technique to emit more conflicts than would normally be expected.

In complex merge cases, bzr merge --lca or bzr merge --weave may give better results. You may wish to bzr revert the working tree and merge again. Alternatively, use bzr remerge on particular conflicted files.

Criss-crosses occur in a branch's history if two branches merge the same thing and then merge one another, or if two branches merge one another at the same time. They can be avoided by having each branch only merge from or into a designated central branch (a "star topology").

Criss-crosses cause problems because of the way merge works. Bazaar's default merge is a three-way merger; in order to merge OTHER into THIS, it must find a basis for comparison, BASE. Using BASE, it can determine whether differences between THIS and OTHER are due to one side adding lines, or from another side removing lines.

Criss-crosses mean there is no good choice for a base. Selecting the recent merge points could cause one side's changes to be silently discarded. Selecting older merge points (which Bazaar does) mean that extra conflicts are emitted.

The weave merge type is not affected by this problem because it uses line-origin detection instead of a basis revision to determine the cause of differences.

End of Line Conversion

EOL conversion is provided as a content filter where Bazaar internally stores a canonical format but outputs a convenience format. See bzr help content-filters for general information about using these.

Note: Content filtering is only supported in recently added formats, e.g. 1.14. Be sure that both the repository and the branch are in a recent format. (Just setting the format on the repository is not enough.) If content filtering does not appear to be working, use 'bzr info -v' to confirm that the branch is using "Working tree format 5" or later.

EOL conversion needs to be enabled for selected file patterns using rules. See bzr help rules for general information on defining rules. Currently, rules are only supported in $BZR_HOME/.bazaar/rules (or %BZR_HOME%/bazaar/2.0/rules on Windows). Branch specific rules will be supported in a future verison of Bazaar.

To configure which files to filter, set eol to one of the values below. (If a value is not set, exact is the default.)

Value Checkout end-of-lines as Commit end-of-lines as
native crlf on Windows, lf otherwise lf
lf lf lf
crlf crlf lf
exact No conversion Exactly as in file

Note: For safety reasons, no conversion is applied to any file where a null byte is detected in the file.

For users working on a cross-platform project, here is a suggested rule to use as a starting point:

[name *]
eol = native

If you have binary files that do not contain a null byte though, be sure to add eol = exact rules for those as well. You can do this by giving more explicit patterns earlier in the rules file. For example:

[name *.png]
eol = exact

[name *]
eol = native

If your working tree is on a network drive shared by users on different operating systems, you typically want to force certain conventions for certain files. In that way, if a file is created with the wrong line endings or line endings get mixed during editing, it gets committed correctly and gets checked out correctly. For example:

[name *.bat]
eol = crlf

[name *.sh]
eol = lf

[name *]
eol = native

If you take the care to create files with their required endings, you can achieve almost the same thing by using eol = exact. It is slightly safer to use lf and crlf though because edits accidentally introducing mixed line endings will be corrected during commit for files with those settings.

If you have sample test data that deliberately has text files with mixed newline conventions, you can ask for those to be left alone like this:

[name test_data/]
eol = exact

[name *]
eol = native

Note that exact does not imply the file is binary but it does mean that no conversion of end-of-lines will be done. (Bazaar currently relies of content analysis to detect binary files for commands like diff. In the future, a binary = true rule may be added but it is not supported yet.)

If you have an existing repository with text files already stored using Windows newline conventions (crlf), then you may want to keep using that convention in the repository. Forcing certain files to this convention may also help users who do not have rules configured. To do this, set eol to one of the values below.

Value Checkout end-of-lines as Commit end-of-lines as
native-with-crlf-in-repo crlf on Windows, lf otherwise crlf
lf-with-crlf-in-repo lf crlf
crlf-with-crlf-in-repo crlf crlf

For users working on an existing project that uses Windows newline conventions in their Bazaar repository, this rule is suggested as a starting point:

[name *]
eol = native-with-crlf-in-repo

For new projects, it is recommended that end-of-lines be stored as lf and that users stick to the basic settings, i.e. native, lf, crlf and exact.

Note: Bazaar's EOL conversion will convert the content of files but never reject files because a given line ending or mixed line endings are found. A precommit hook should be used if you wish to validate (and not just convert) content before committing.

Storage Formats

To ensure that older clients do not access data incorrectly, Bazaar's policy is to introduce a new storage format whenever new features requiring new metadata are added. New storage formats may also be introduced to improve performance and scalability.

Use the following guidelines to select a format (stopping as soon as a condition is true):

  • If you are working on an existing project, use whatever format that project is using. (Bazaar will do this for you by default).
  • If you are using bzr-svn to interoperate with a Subversion repository, use 1.14-rich-root.
  • If you are working on a project with big trees (5000+ paths) or deep history (5000+ revisions), use 1.14.
  • Otherwise, use the default format - it is good enough for most projects.

If some of your developers are unable to use the most recent version of Bazaar (due to distro package availability say), be sure to adjust the guidelines above accordingly. For example, you may need to select 1.9 instead of 1.14 if your project has standardized on Bazaar 1.13.1 say.

Note: Many of the currently supported formats have two variants: a plain one and a rich-root one. The latter include an additional field about the root of the tree. There is no performance cost for using a rich-root format but you cannot easily merge changes from a rich-root format into a plain format. As a consequence, moving a project to a rich-root format takes some co-ordination in that all contributors need to upgrade their repositories around the same time. (It is for this reason that we have delayed making a rich-root format the default so far, though we will do so at some appropriate time in the future.)

See bzr help current-formats for the complete list of currently supported formats. See bzr help other-formats for descriptions of any available experimental and deprecated formats.

Patterns

Bazaar uses patterns to match files at various times. For example, the add command skips over files that match ignore patterns and preferences can be associated with files using rule patterns. The pattern syntax is described below.

Trailing slashes on patterns are ignored. If the pattern contains a slash or is a regular expression, it is compared to the whole path from the branch root. Otherwise, it is compared to only the last component of the path. To match a file only in the root directory, prepend './'. Patterns specifying absolute paths are not allowed.

Patterns may include globbing wildcards such as:

? - Matches any single character except '/'
* - Matches 0 or more characters except '/'
/**/ - Matches 0 or more directories in a path
[a-z] - Matches a single character from within a group of characters

Patterns may also be Python regular expressions. Regular expression patterns are identified by a 'RE:' prefix followed by the regular expression. Regular expression patterns may not include named or numbered groups.

Repositories

Repositories in Bazaar are where committed information is stored. There is a repository associated with every branch.

Repositories are a form of database. Bzr will usually maintain this for good performance automatically, but in some situations (e.g. when doing very many commits in a short time period) you may want to ask bzr to optimise the database indices. This can be done by the 'bzr pack' command.

By default just running 'bzr init' will create a repository within the new branch but it is possible to create a shared repository which allows multiple branches to share their information in the same location. When a new branch is created it will first look to see if there is a containing shared repository it can use.

When two branches of the same project share a repository, there is generally a large space saving. For some operations (e.g. branching within the repository) this translates in to a large time saving.

To create a shared repository use the init-repository command (or the alias init-repo). This command takes the location of the repository to create. This means that 'bzr init-repository repo' will create a directory named 'repo', which contains a shared repository. Any new branches that are created in this directory will then use it for storage.

It is a good idea to create a repository whenever you might create more than one branch of a project. This is true for both working areas where you are doing the development, and any server areas that you use for hosting projects. In the latter case, it is common to want branches without working trees. Since the files in the branch will not be edited directly there is no need to use up disk space for a working tree. To create a repository in which the branches will not have working trees pass the '--no-trees' option to 'init-repository'.

Related commands:

init-repository   Create a shared repository. Use --no-trees to create one
                  in which new branches won't get a working tree.

Rules

Introduction

Rules are defined in ini file format where the sections are file glob patterns and the contents of each section are the preferences for files matching that pattern(s). For example:

[name *.bat]
eol = dos

[name *.html *.xml]
keywords = xml_escape

Preferences like these are useful for commands and plugins wishing to provide custom behaviour for selected files. For more information on end of line conversion see bzr help eol. Keyword support is provided by the bzr-keywords plugin (http://launchpad.net/bzr-keywords).

Files

Default rules for all branches are defined in the optional file BZR_HOME/rules.

Rule Patterns

Patterns are ordered and searching stops as soon as one matches. As a consequence, more explicit patterns should be placed towards the top of the file. Rule patterns use exactly the same conventions as ignore patterns. See bzr help patterns for details.

Note: Patterns containing square brackets or spaces should be surrounded in quotes to ensure they are correctly parsed.

Standalone Trees

A standalone tree is a working tree with an associated repository. It is an independently usable branch, with no dependencies on any other. Creating a standalone tree (via bzr init) is the quickest way to put an existing project under version control.

Related Commands:

init    Make a directory into a versioned branch.

Branches out of sync

When reconfiguring a checkout, tree or branch into a lightweight checkout, a local branch must be destroyed. (For checkouts, this is the local branch that serves primarily as a cache.) If the branch-to-be-destroyed does not have the same last revision as the new reference branch for the lightweight checkout, data could be lost, so Bazaar refuses.

How you deal with this depends on why the branches are out of sync.

If you have a checkout and have done local commits, you can get back in sync by running "bzr update" (and possibly "bzr commit").

If you have a branch and the remote branch is out-of-date, you can push the local changes using "bzr push". If the local branch is out of date, you can do "bzr pull". If both branches have had changes, you can merge, commit and then push your changes. If you decide that some of the changes aren't useful, you can "push --overwrite" or "pull --overwrite" instead.

Working Trees

A working tree is the contents of a branch placed on disk so that you can see the files and edit them. The working tree is where you make changes to a branch, and when you commit the current state of the working tree is the snapshot that is recorded in the commit.

When you push a branch to a remote system, a working tree will not be created. If one is already present the files will not be updated. The branch information will be updated and the working tree will be marked as out-of-date. Updating a working tree remotely is difficult, as there may be uncommitted changes or the update may cause content conflicts that are difficult to deal with remotely.

If you have a branch with no working tree you can use the 'checkout' command to create a working tree. If you run 'bzr checkout .' from the branch it will create the working tree. If the branch is updated remotely, you can update the working tree by running 'bzr update' in that directory.

If you have a branch with a working tree that you do not want the 'remove-tree' command will remove the tree if it is safe. This can be done to avoid the warning about the remote working tree not being updated when pushing to the branch. It can also be useful when working with a '--no-trees' repository (see 'bzr help repositories').

If you want to have a working tree on a remote machine that you push to you can either run 'bzr update' in the remote branch after each push, or use some other method to update the tree during the push. There is an 'rspush' plugin that will update the working tree using rsync as well as doing a push. There is also a 'push-and-update' plugin that automates running 'bzr update' via SSH after each push.

Useful commands:

checkout     Create a working tree when a branch does not have one.
remove-tree  Removes the working tree from a branch when it is safe to do so.
update       When a working tree is out of sync with it's associated branch
             this will update the tree to match the branch.

Lists

Authentication Settings

Intent

Many different authentication policies can be described in the authentication.conf file but a particular user should need only a few definitions to cover his needs without having to specify a user and a password for every branch he uses.

The definitions found in this file are used to find the credentials to use for a given url. The same credentials can generally be used for as many branches as possible by grouping their declaration around the remote servers that need them. It's even possible to declare credentials that will be used by different servers.

The intent is to make this file as small as possible to minimize maintenance.

Once the relevant credentials are declared in this file you may use branch urls without embedding passwords (security hazard) or even users (enabling sharing of your urls with others).

Instead of using:

bzr branch ftp://joe:secret@host.com/path/to/my/branch

you simply use:

bzr branch ftp://host.com/path/to/my/branch

provided you have created the following authentication.conf file:

[myprojects]
scheme=ftp
host=host.com
user=joe
password=secret

Authentication definitions

There are two kinds of authentication used by the various schemes supported by bzr:

  1. user and password

FTP needs a (user, password) to authenticate against a host SFTP can use either a password or a host key to authenticate. However, ssh agents are a better, more secure solution. So we have chosen to not provide our own less secure method.

  1. user, realm and password

HTTP and HTTPS needs a (user, realm, password) to authenticate against a host. But, by using .htaccess files, for example, it is possible to define several (user, realm, password) for a given host. So what is really needed is (user, password, host, path). The realm is not taken into account in the defitions, but will displayed if bzr prompts you for a password.

HTTP proxy can be handled as HTTP (or HTTPS) by explicitely specifying the appropriate port.

To take all schemes into account, the password will be deduced from a set of authentication definitions (scheme, host, port, path, user, password).

  • scheme: can be empty (meaning the rest of the definition can be used for any scheme), SFTP and bzr+ssh should not be used here, ssh should be used instead since this is the real scheme regarding authentication,
  • host: can be empty (to act as a default for any host),
  • port can be empty (useful when an host provides several servers for the same scheme), only numerical values are allowed, this should be used only when the server uses a port different than the scheme standard port,
  • path: can be empty (FTP or SFTP will never user it),
  • user: can be empty (bzr will defaults to python's getpass.get_user()),
  • password: can be empty if you prefer to always be prompted for your password.

Multiple definitions can be provided and, for a given URL, bzr will select a (user [, password]) based on the following rules :

  1. the first match wins,
  2. empty fields match everything,
  3. scheme matches even if decorators are used in the requested URL,
  4. host matches exactly or act as a domain if it starts with '.' (project.bzr.sf.net will match .bzr.sf.net but projectbzr.sf.net will not match bzr.sf.net).
  5. port matches if included in the requested URL (exact matches only)
  6. path matches if included in the requested URL (and by rule #2 above, empty paths will match any provided path).

File format

The general rules for configuration files apply except for the variable policies.

Each section describes an authentication definition.

The section name is an arbitrary string, only the DEFAULT value is reserved and should appear as the last section.

Each section should define:

  • user: the login to be used,

Each section could define:

  • host: the remote server,
  • port: the port the server is listening,
  • path: the branch location,
  • password: the password.

Examples

Personal projects hosted outside

All connections are done with the same user (the remote one for which the default bzr one is not appropriate) and the password is always prompted with some exceptions:

# Pet projects on hobby.net
[hobby]
host=r.hobby.net
user=jim
password=obvious1234

# Home server
[home]
scheme=https
host=home.net
user=joe
password=1essobV10us

[DEFAULT]
# Our local user is barbaz, on all remote sites we're known as foobar
user=foobar

Source hosting provider

In the shp.net (fictious) domain, each project has its own site:

[shpnet domain]
# we use sftp, but ssh is the scheme used for authentication
scheme=ssh
# The leading '.' ensures that 'shp.net' alone doesn't match
host=.shp.net
user=joe
# bzr don't support supplying a password for sftp,
# consider using an ssh agent if you don't want to supply
# a password interactively. (pageant, ssh-agent, etc)

HTTPS, SFTP servers and their proxy

At company.com, the server hosting release and integration branches is behind a proxy, and the two branches use different authentication policies:

[reference code]
scheme=https
host=dev.company.com
path=/dev
user=user1
password=pass1

# development branches on dev server
[dev]
scheme=ssh # bzr+ssh and sftp are available here
host=dev.company.com
path=/dev/integration
user=user2

# proxy
[proxy]
scheme=http
host=proxy.company.com
port=3128
user=proxyuser1
password=proxypass1

Planned enhancements

The following are not yet implemented but planned as parts of a work in progress:

  • add a password_encoding field allowing:
    • storing the passwords in various obfuscating encodings (base64 for one),
    • delegate password storage to plugins (.netrc for example).
  • update the credentials when the user is prompted for user or password,
  • add a verify_certificates field for HTTPS.

The password_encoding and verify_certificates fields are recognized but ignored in the actual implementation.

Bug Tracker Settings

When making a commit, metadata about bugs fixed by that change can be recorded by using the --fixes option. For each bug marked as fixed, an entry is included in the 'bugs' revision property stating '<url> <status>'. (The only status value currently supported is fixed.)

The --fixes option allows you to specify a bug tracker and a bug identifier rather than a full URL. This looks like

bzr commit --fixes <tracker>:<id>

where "<tracker>" is an identifier for the bug tracker, and "<id>" is the identifier for that bug within the bugtracker, usually the bug number.

Bazaar knows about a few bug trackers that have many users. If you use one of these bug trackers then there is no setup required to use this feature, you just need to know the tracker identifier to use. These are the bugtrackers that are built in:

URL | Abbreviation | Example https://bugs.launchpad.net/ | lp | lp:12345 http://bugs.debian.org/ | deb | deb:12345 http://bugzilla.gnome.org/ | gnome | gnome:12345

For the bug trackers not listed above configuration is required. Support for generating the URLs for any project using Bugzilla or Trac is built in, along with a template mechanism for other bugtrackers with simple URL schemes. If your bug tracker can't be described by one of the schemes described below then you can write a plugin to support it.

If you use Bugzilla or Trac, then you only need to set a configuration variable which contains the base URL of the bug tracker. These options can go into bazaar.conf, branch.conf or into a branch-specific configuration section in locations.conf. You can set up these values for each of the projects you work on.

Note: As you provide a short name for each tracker, you can specify one or more bugs in one or more trackers at commit time if you wish.

Launchpad

Use bzr commit --fixes lp:2 to record that this commit fixes bug 2.

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.

bugtracker_<tracker_abbrevation>_url

If present, the location of a generic bug tracker instance referred to by <tracker_abbreviation>. The location must contain an {id} placeholder, which will be replaced by a specific bug ID. 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:

bugtracker_python_url = http://bugs.python.org/issue{id}

would allow bzr commit --fixes python:1234 to mark bug 1234 in Python's Roundup bug tracker as fixed, or:

bugtracker_cpan_url = http://rt.cpan.org/Public/Bug/Display.html?id={id}

for CPAN's RT bug tracker.

Configuration Settings

Environment settings

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 (normally, exit with a core dump)
  • 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.

Configuration files

Location

Configuration files are located in $HOME/.bazaar on Linux/Unix and C:\Documents and Settings\<username>\Application Data\Bazaar\2.0 on Windows. (You can check the location for your system by using bzr version.)

There are three primary configuration files in this location:

  • bazaar.conf describes default configuration options,
  • locations.conf describes configuration information for specific branch locations,
  • authentication.conf describes credential information for remote servers.

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 headers for bazaar.conf currently are [DEFAULT] and [ALIASES]. Section headers are 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

bazaar.conf allows two sections: [DEFAULT] and [ALIASES]. The 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

The branch location configuration file, locations.conf

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

The authentication configuration file, authentication.conf

authentication.conf allows one to specify credentials for remote servers. This can be used for all the supported transports and any part of bzr that requires authentication (smtp for example).

The syntax of the file obeys the same rules as the others except for the variable policies which don't apply.

For more information on the possible uses of the authentication configuration file see Authentication Settings.

Common variable options

debug_flags

A comma-separated list of debugging options to turn on. The same values can be used as with the -D command-line option (see help global-options). For example:

debug_flags = hpss

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 the VISUAL and EDITOR environment variables.

log_format

The default log format to use. Standard log formats are long, short and line. Additional formats may be provided by plugins. The default value is long.

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:

claws:Use Claws. This skips a dialog for attaching files.
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 type specific options

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

push_strict

If present, defines the --strict option default value for checking uncommitted changes before pushing.

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.

send_strict

If present, defines the --strict option default value for checking uncommitted changes before sending a merge directive.

Conflicts Types

Some operations, like merge, revert and pull, modify the contents of your working tree. These modifications are programmatically generated, and so they may conflict with the current state of your working tree. Many kinds of changes can be combined programmatically, but sometimes only a human can determine the right thing to do. When this happens Bazaar will inform you that there is a conflict and then ask you to resolve it. The command to tell Bazaar a conflict is resolved is resolve, but you must perform some action before you can do this.

Each type of conflict is explained below, and the action which must be done to resolve the conflict is outlined.

Text conflicts

Typical message:

Text conflict in FILE

These are produced when a text merge cannot completely reconcile two sets of text changes. Bazaar will emit files for each version with the extensions THIS, OTHER, and BASE. THIS is the version of the file from the target tree, i.e. the tree that you are merging changes into. OTHER is the version that you are merging into the target. BASE is an older version that is used as a basis for comparison.

In the main copy of the file, Bazaar will include all the changes that it could reconcile, and any un-reconciled conflicts are surrounded by "herringbone" markers like <<<<<<<.

Say the initial text is "The project leader released it.", and THIS modifies it to "Martin Pool released it.", while OTHER modifies it to "The project leader released Bazaar." A conflict would look like this:

<<<<<<< TREE
Martin Pool released it.
=======
The project leader released Bazaar.
>>>>>>> MERGE-SOURCE

The correct resolution would be "Martin Pool released Bazaar."

You can handle text conflicts either by editing the main copy of the file, or by invoking external tools on the THIS, OTHER and BASE versions. It's worth mentioning that resolving text conflicts rarely involves picking one set of changes over the other. More often, the two sets of changes must be intelligently combined.

If you edit the main copy, be sure to remove the herringbone markers. When you are done editing, the file should look like it never had a conflict, and be ready to commit.

When you have resolved text conflicts, just run "bzr resolve", and Bazaar will auto-detect which conflicts you have resolved.

Content conflicts

Typical message:

Contents conflict in FILE

This conflict happens when there are conflicting changes in the target tree and the merge source, but the conflicted items are not text files. They may be binary files, or symlinks, or directories. It can even happen with files that are deleted on one side, and modified on the other.

Like text conflicts, Bazaar will emit THIS, OTHER and BASE files. (They may be regular files, symlinks or directories). But it will not include a "main copy" of the file with herringbone conflict markers. It will appear that the "main copy" has been renamed to THIS or OTHER.

To resolve this, use "bzr mv" to rename the file back to its normal name, and combine the changes manually. When you are satisfied, run "bzr resolve FILE". Bazaar cannot auto-detect when conflicts of this kind have been resolved.

Duplicate paths

Typical message:

Conflict adding file FILE.  Moved existing file to FILE.moved.

Sometimes Bazaar will attempt to create a file using a pathname that has already been used. The existing file will be renamed to "FILE.moved". If you wish, you can rename either one of these files, or combine their contents. When you are satisfied, you can run "bzr resolve FILE" to mark the conflict as resolved.

Unversioned parent

Typical message:

Conflict because FILE is not versioned, but has versioned children.

Sometimes Bazaar will attempt to create a file whose parent directory is not versioned. This happens when the directory has been deleted in the target, but has a new child in the source, or vice versa. In this situation, Bazaar will version the parent directory as well. Resolving this issue depends very much on the particular scenario. You may wish to rename or delete either the file or the directory. When you are satisfied, you can run "bzr resolve FILE" to mark the conflict as resolved.

Missing parent

Typical message:

Conflict adding files to FILE.  Created directory.

This happens when a file has been deleted in the target, but has new children in the source. This is similar to the "unversioned parent" conflict, except that the parent directory does not exist, instead of just being unversioned. In this situation, Bazaar will create the missing parent. Resolving this issue depends very much on the particular scenario. You may wish to rename or delete either the file or the directory. When you are satisfied, you can run "bzr resolve FILE" to mark the conflict as resolved.

Deleting parent

Typical message:

Conflict: can't delete FILE because it is not empty.  Not deleting.

This is the opposite of "missing parent". A directory is deleted in the source, but has new children in the target. Bazaar will retain the directory. Resolving this issue depends very much on the particular scenario. You may wish to rename or delete either the file or the directory. When you are satisfied, you can run "bzr resolve FILE" to mark the conflict as resolved.

Path conflict

Typical message:

Path conflict: PATH1 / PATH2

This happens when the source and target have each modified the name or parent directory of a file. Bazaar will use the path elements from the source. You can rename the file, and once you have, run "bzr resolve FILE" to mark the conflict as resolved.

Parent loop

Typical message:

Conflict moving FILE into DIRECTORY.  Cancelled move.

This happens when the source and the target have each moved directories, so that, if the change could be applied, a directory would be contained by itself. For example:

$ bzr init
$ bzr mkdir a
$ bzr mkdir b
$ bzr commit -m "BASE"
$ bzr branch . ../other
$ bzr mv a b
$ bzr commit -m "THIS"
$ bzr mv ../other/b ../other/a
$ bzr commit ../other -m "OTHER"
$ bzr merge ../other

In this situation, Bazaar will cancel the move, and leave "a" in "b". You can rename the directories if you like, and once you have, run "bzr resolve FILE" to mark the conflict as resolved.

Non-directory parent

Typical message:

Conflict: FILE.new is not a directory, but has files in it.
Created directory.

This happens when one side has added files to a directory, and the othe side has changed the directory into a file or symlink. For example:

$ bzr init
$ bzr mkdir a
$ bzr commit -m "BASE"
$ bzr branch . ../other
$ rmdir a
$ touch a
$ bzr commit -m "THIS"
$ bzr mkdir ../other/a/b
$ bzr commit ../other -m "OTHER"
$ bzr merge ../other

MalformedTransform

It is possible (though very rare) for Bazaar to raise a MalformedTransform exception. This means that Bazaar encountered a filesystem conflict that it was unable to resolve. This usually indicates a bug. Please let us know if you encounter this. Our bug tracker is at https://launchpad.net/bzr/+bugs

Current Storage Formats

pack-0.92:(native) (default) New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack-experimental. For more information, see http://doc.bazaar- vcs.org/latest/developers/packrepo.html.
rich-root-pack:(native) New in 1.0: A variant of pack-0.92 that supports rich- root data (needed for bzr-svn and bzr-git).
1.6:(native) A format that allows a branch to indicate that there is another (stacked) repository that should be used to access data that is not present locally.
1.6.1-rich-root:
 (native) A variant of 1.6 that supports rich-root data (needed for bzr-svn and bzr-git).
1.9:(native) A repository format using B+tree indexes. These indexes are smaller in size, have smarter caching and provide faster performance for most operations.
1.9-rich-root:(native) A variant of 1.9 that supports rich-root data (needed for bzr-svn and bzr-git).
1.14:(native) A working-tree format that supports content filtering.
1.14-rich-root:(native) A variant of 1.14 that supports rich-root data (needed for bzr-svn and bzr-git).
default-rich-root:
 (native) Default format, rich root variant. (needed for bzr-svn and bzr-git).

See bzr help formats for more about storage formats.

Debug Flags

These flags can be passed on the bzr command line or (without the -D prefix) put in the debug_flags variable in bazaar.conf.

-Dauth Trace authentication sections used.
-Derror Instead of normal error handling, always print a traceback on error.
-Devil Capture call sites that do expensive or badly-scaling operations.
-Dfetch Trace history copying between repositories.
-Dfilters Emit information for debugging content filtering.
-Dgraph Trace graph traversal.
-Dhashcache Log every time a working file is read to determine its hash.
-Dhooks Trace hook execution.
-Dhpss Trace smart protocol requests and responses.
-Dhpssdetail More hpss details.
-Dhpssvfs Traceback on vfs access to Remote objects.
-Dhttp Trace http connections, requests and responses
-Dindex Trace major index operations.
-Dknit Trace knit operations.
-Dlock Trace when lockdir locks are taken or released.
-Dmerge Emit information for debugging merges.
-Dpack Emit information about pack operations.
-Dsftp Trace SFTP internals.

Diverged Branches

When Bazaar tries to push one branch onto another, it requires that the destination branch must be ready to receive the source branch. If this isn't the case, then we say that the branches have diverged. Branches are considered diverged if the destination branch's most recent commit is one that has not been merged (directly or indirectly) by the source branch. To recover from diverged branches, one must merge the missing revisions into the source branch.

This situation commonly arises when using a centralized workflow with local commits. If someone else has committed new work to the mainline since your last pull and you have local commits that have not yet been pushed to the mainline, then your local branch and the mainline have diverged.

Discovering What Has Diverged

The bzr missing command is used to find out what revisions are in another branch that are not present in the current branch, and vice-versa. It shows a summary of which extra revisions exist in each branch. If you want to see the precise effects of those revisions, you can use bzr diff --old=other_branch to show the differences between other_branch and your current branch.

A Solution

The solution is to merge the revisions from the mainline into your local branch. To do so, use bzr merge to get the new revisions from the mainline. This merge may result in conflicts if the other developer's changes overlap with your changes. These conflicts should be resolved before continuing. After any conflicts have been resolved, or even if there were no conflicts, Bazaar requires that you explicitly commit these new revisions to your local branch. This requirement gives you an opportunity to test the resulting working tree for correctness, since the merged revisions could have made arbitrary changes. After testing, you should commit the merge using bzr commit. This clears up the diverged branches situation. Your local branch can now be pushed to the mainline.

Environment Variables

BZRPATH Path where bzr is to look for shell plugin external commands.
BZR_EMAIL E-Mail address of the user. Overrides EMAIL.
EMAIL E-Mail address of the user.
BZR_EDITOR Editor for editing commit messages. Overrides EDITOR.
EDITOR Editor for editing commit messages.
BZR_PLUGIN_PATH Paths where bzr should look for plugins.
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
BZR_REMOTE_PATH Full name of remote 'bzr' command (for bzr+ssh:// URLs).
BZR_SSH SSH client: paramiko (default), openssh, ssh, plink.
BZR_LOG Location of .bzr.log (use '/dev/null' to suppress log).
BZR_LOG (Win32) Location of .bzr.log (use 'NUL' to suppress log).

Files

On Linux:~/.bazaar/bazaar.conf
On Windows:C:\Documents and Settings\username\Application Data\bazaar\2.0\bazaar.conf

Contains the user's default configuration. The section [DEFAULT] is used to define general configuration that will be applied everywhere. The section [ALIASES] can be used to create command aliases for commonly used options.

A typical config file might look something like:

[DEFAULT]
email=John Doe <jdoe@isp.com>

[ALIASES]
commit = commit --strict
log10 = log --short -r -10..-1

Global Options

These options may be used with any command, and may appear in front of any command. (e.g. "bzr --profile help").

--version Print the version number. Must be supplied before the command.
--no-aliases Do not process command aliases when running this command.
--builtin Use the built-in version of a command, not the plugin version. This does not suppress other plugin effects.
--no-plugins Do not process any plugins.
--profile Profile execution using the hotshot profiler.
--lsprof Profile execution using the lsprof profiler.
--lsprof-file Profile execution using the lsprof profiler, and write the results to a specified file. If the filename ends with ".txt", text format will be used. If the filename either starts with "callgrind.out" or end with ".callgrind", the output will be formatted for use with KCacheGrind. Otherwise, the output will be a pickle.
--coverage Generate line coverage report in the specified directory.

See doc/developers/profiling.txt for more information on profiling. A number of debug flags are also available to assist troubleshooting and development. See bzr help debug-flags.

Hooks

Introduction

A hook of type xxx of class yyy needs to be registered using:

yyy.hooks.install_named_hook("xxx", ...)

See Using hooks in the User Guide for examples.

The class that contains each hook is given before the hooks it supplies. For instance, BranchHooks as the class is the hooks class for bzrlib.branch.Branch.hooks.

Each description also indicates whether the hook runs on the client (the machine where bzr was invoked) or the server (the machine addressed by the branch URL). These may be, but are not necessarily, the same machine.

Plugins (including hooks) are run on the server if all of these is true:

  • The connection is via a smart server (accessed with a URL starting with "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://" URL when a smart server is available via HTTP).
  • The hook is either server specific or part of general infrastructure rather than client specific code (such as commit).

BranchHooks

open

Introduced in: 1.8 Deprecated in: Not deprecated

Called with the Branch object that has been opened after a branch is opened.

post_change_branch_tip

Introduced in: 1.4 Deprecated in: Not deprecated

Called in bzr client and server after a change to the tip of a branch is made. post_change_branch_tip is called with a bzrlib.branch.ChangeBranchTipParams. Note that push, pull, commit, uncommit will all trigger this hook.

post_commit

Introduced in: 0.15 Deprecated in: Not deprecated

Called in the bzr client after a commit has completed. post_commit is called with (local, master, old_revno, old_revid, new_revno, new_revid). old_revid is NULL_REVISION for the first commit to a branch.

post_pull

Introduced in: 0.15 Deprecated in: Not deprecated

Called after a pull operation completes. post_pull is called with a bzrlib.branch.PullResult object and only runs in the bzr client.

post_push

Introduced in: 0.15 Deprecated in: Not deprecated

Called after a push operation completes. post_push is called with a bzrlib.branch.BranchPushResult object and only runs in the bzr client.

post_uncommit

Introduced in: 0.15 Deprecated in: Not deprecated

Called in the bzr client after an uncommit completes. post_uncommit is called with (local, master, old_revno, old_revid, new_revno, new_revid) where local is the local branch or None, master is the target branch, and an empty branch receives new_revno of 0, new_revid of None.

pre_change_branch_tip

Introduced in: 1.6 Deprecated in: Not deprecated

Called in bzr client and server before a change to the tip of a branch is made. pre_change_branch_tip is called with a bzrlib.branch.ChangeBranchTipParams. Note that push, pull, commit, uncommit will all trigger this hook.

pre_commit

Introduced in: 0.91 Deprecated in: Not deprecated

Called after a commit is calculated but before it is is completed. pre_commit is called with (local, master, old_revno, old_revid, future_revno, future_revid, tree_delta, future_tree). old_revid is NULL_REVISION for the first commit to a branch, tree_delta is a TreeDelta object describing changes from the basis revision. hooks MUST NOT modify this delta. future_tree is an in-memory tree obtained from CommitBuilder.revision_tree() and hooks MUST NOT modify this tree.

set_rh

Introduced in: 0.15 Deprecated in: Not deprecated

Invoked whenever the revision history has been set via set_revision_history. The api signature is (branch, revision_history), and the branch will be write-locked. The set_rh hook can be expensive for bzr to trigger, a better hook to use is Branch.post_change_branch_tip.

transform_fallback_location

Introduced in: 1.9 Deprecated in: Not deprecated

Called when a stacked branch is activating its fallback locations. transform_fallback_location is called with (branch, url), and should return a new url. Returning the same url allows it to be used as-is, returning a different one can be used to cause the branch to stack on a closer copy of that fallback_location. Note that the branch cannot have history accessing methods called on it during this hook because the fallback locations have not been activated. When there are multiple hooks installed for transform_fallback_location, all are called with the url returned from the previous hook.The order is however undefined.

BzrDirHooks

pre_open

Introduced in: 1.14 Deprecated in: Not deprecated

Invoked before attempting to open a BzrDir with the transport that the open will use.

CommandHooks

extend_command

Introduced in: 1.13 Deprecated in: Not deprecated

Called after creating a command object to allow modifications such as adding or removing options, docs etc. Called with the new bzrlib.commands.Command object.

get_command

Introduced in: 1.17 Deprecated in: Not deprecated

Called when creating a single command. Called with (cmd_or_None, command_name). get_command should either return the cmd_or_None parameter, or a replacement Command object that should be used for the command. Note that the Command.hooks hooks are core infrastructure. Many users will prefer to use bzrlib.commands.register_command or plugin_cmds.register_lazy.

get_missing_command

Introduced in: 1.17 Deprecated in: Not deprecated

Called when creating a single command if no command could be found. Called with (command_name). get_missing_command should either return None, or a Command object to be used for the command.

list_commands

Introduced in: 1.17 Deprecated in: Not deprecated

Called when enumerating commands. Called with a set of cmd_name strings for all the commands found so far. This set is safe to mutate - e.g. to remove a command. list_commands should return the updated set of command names.

InfoHooks

repository

Introduced in: 1.15 Deprecated in: Not deprecated

Invoked when displaying the statistics for a repository. repository is called with a statistics dictionary as returned by the repository and a file-like object to write to.

LockHooks

lock_acquired

Introduced in: 1.8 Deprecated in: Not deprecated

Called with a bzrlib.lock.LockResult when a physical lock is acquired.

lock_broken

Introduced in: 1.15 Deprecated in: Not deprecated

Called with a bzrlib.lock.LockResult when a physical lock is broken.

lock_released

Introduced in: 1.8 Deprecated in: Not deprecated

Called with a bzrlib.lock.LockResult when a physical lock is released.

MergeDirectiveHooks

merge_request_body

Introduced in: 1.15 Deprecated in: Not deprecated

Called with a MergeRequestBodyParams when a body is needed for a merge request. Callbacks must return a body. If more than one callback is registered, the output of one callback is provided to the next.

MessageEditorHooks

commit_message_template

Introduced in: 1.10 Deprecated in: Not deprecated

Called when a commit message is being generated. commit_message_template is called with the bzrlib.commit.Commit object and the message that is known so far. commit_message_template must return a new message to use (which could be the same as it was given. When there are multiple hooks registered for commit_message_template, they are chained with the result from the first passed into the second, and so on.

MutableTreeHooks

start_commit

Introduced in: 1.4 Deprecated in: Not deprecated

Called before a commit is performed on a tree. The start commit hook is able to change the tree before the commit takes place. start_commit is called with the bzrlib.tree.MutableTree that the commit is being performed on.

SmartClientHooks

call

Introduced in: unknown Deprecated in: Not deprecated

Called when the smart client is submitting a request to the smart server. Called with a bzrlib.smart.client.CallHookParams object. Streaming request bodies, and responses, are not accessible.

SmartServerHooks

server_started

Introduced in: 0.16 Deprecated in: Not deprecated

Called by the bzr server when it starts serving a directory. server_started is called with (backing urls, public url), where backing_url is a list of URLs giving the server-specific directory locations, and public_url is the public URL for the directory being served.

server_stopped

Introduced in: 0.16 Deprecated in: Not deprecated

Called by the bzr server when it stops serving a directory. server_stopped is called with the same parameters as the server_started hook: (backing_urls, public_url).

RioVersionInfoBuilderHooks

revision

Introduced in: 1.15 Deprecated in: Not deprecated

Invoked when adding information about a revision to the RIO stanza that is printed. revision is called with a revision object and a RIO stanza.

Log formats

A log format controls how information about each revision is displayed. The standard log formats are compared below:

Feature                 long           short         line
----------------------  -------------  ------------  -------------------
design goal             detailed view  concise view  1 revision per line
committer               name+email     name only     name only
author                  name+email     -             -
date-time format        full           date only     date only
commit message          full           full          top line
tags                    yes            yes           yes
merges indicator        -              yes           -
status/delta            optional       optional      -
diff/patch              optional       optional      -
revision-id             optional       optional      -
branch nick             yes            -             -
foreign vcs properties  yes            yes           -
preferred levels        all            1             1

The default format is long. To change this, define the log_format setting in the [DEFAULT] section of bazaar.conf like this (say):

[DEFAULT]
log_format = short

Alternatively, to change the log format used for a given query, use the --long, --short or --line options.

If one of the standard log formats does not meet your needs, additional formats can be provided by plugins.

Other Storage Formats

Experimental formats are shown below.

development-rich-root:
 (native) Current development format. Supports rich roots. Can convert data to and from rich-root-pack (and anything compatible with rich-root-pack) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc.bazaar-vcs.org/latest/developers/development-repo.html before use.
development-subtree:
 (native) Current development format, subtree variant. Can convert data to and from pack-0.92-subtree (and anything compatible with pack-0.92-subtree) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc .bazaar-vcs.org/latest/developers/development-repo.html before use.
2a:(native) First format for bzr 2.0 series. Uses group-compress storage. Provides rich roots which are a one-way transition.

Deprecated formats are shown below.

weave:(native) Pre-0.8 format. Slower than knit and does not support checkouts or shared repositories.
metaweave:(native) Transitional format in 0.8. Slower than knit.
knit:(native) Format using knits. Recommended for interoperation with bzr <= 0.14.
dirstate:(native) New in 0.15: Fast local operations. Compatible with bzr 0.8 and above when accessed over the network.
dirstate-tags:(native) New in 0.15: Fast local operations and improved scaling for network operations. Additionally adds support for tags. Incompatible with bzr < 0.15.
rich-root:(native) New in 1.0. Better handling of tree roots. Incompatible with bzr < 1.0.

See bzr help formats for more about storage formats.

Revision Identifiers

A revision identifier refers to a specific state of a branch's history. It can be a revision number, or a keyword followed by ':' and often other parameters. Some examples of identifiers are '3', 'last:1', 'before:yesterday' and 'submit:'.

If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a revision range. Examples: '3647..3649', 'date:yesterday..-1' and 'branch:/path/to/branch1/..branch:/branch2' (note that there are no quotes or spaces around the '..').

Ranges are interpreted differently by different commands. To the "log" command, a range is a sequence of log messages, but to the "diff" command, the range denotes a change between revisions (and not a sequence of changes). In addition, "log" considers a closed range whereas "diff" and "merge" consider it to be open-ended, that is, they include one end but not the other. For example: "bzr log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649, while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and 3649, but not 3647.

The keywords used as revision selection methods are the following:

revid:Selects a revision using the revision id.
submit:Selects a common ancestor with the submit branch.
ancestor:Selects a common ancestor with a second branch.
date:Selects a revision on the basis of a datestamp.
branch:Selects the last revision of a specified branch.
tag:Selects a revision identified by a tag name.
revno:Selects a revision using a number.
before:Selects the parent of the revision specified.
last:Selects the nth revision from the end.

In addition, plugins can provide other keywords.

A detailed description of each keyword is given below.

revid:

Supply a specific revision id, that can be used to specify any revision id in the ancestry of the branch. Including merges, and pending merges. Examples:

revid:aaaa@bbbb-123456789 -> Select revision 'aaaa@bbbb-123456789'
submit:

Diffing against this shows all the changes that were made in this branch, and is a good predictor of what merge will do. The submit branch is used by the bundle and merge directive commands. If no submit branch is specified, the parent branch is used instead.

The common ancestor is the last revision that existed in both branches. Usually this is the branch point, but it could also be a revision that was merged.

Examples:

$ bzr diff -r submit:
ancestor:

Supply the path to a branch to select the common ancestor.

The common ancestor is the last revision that existed in both branches. Usually this is the branch point, but it could also be a revision that was merged.

This is frequently used with 'diff' to return all of the changes that your branch introduces, while excluding the changes that you have not merged from the remote branch.

Examples:

ancestor:/path/to/branch
$ bzr diff -r ancestor:../../mainline/branch
date:

Supply a datestamp to select the first revision that matches the date. Date can be 'yesterday', 'today', 'tomorrow' or a YYYY-MM-DD string. Matches the first entry after a given date (either at midnight or at a specified time).

One way to display all the changes since yesterday would be:

bzr log -r date:yesterday..

Examples:

date:yesterday            -> select the first revision since yesterday
date:2006-08-14,17:10:14  -> select the first revision after
                             August 14th, 2006 at 5:10pm.
branch:

Supply the path to a branch to select its last revision.

Examples:

branch:/path/to/branch
tag:

Tags are stored in the branch and created by the 'tag' command.

revno:

Use an integer to specify a revision in the history of the branch. Optionally a branch can be specified. The 'revno:' prefix is optional. A negative number will count from the end of the branch (-1 is the last revision, -2 the previous one). If the negative number is larger than the branch's history, the first revision is returned. Examples:

revno:1                   -> return the first revision of this branch
revno:3:/path/to/branch   -> return the 3rd revision of
                             the branch '/path/to/branch'
revno:-1                  -> The last revision in a branch.
-2:http://other/branch    -> The second to last revision in the
                             remote branch.
-1000000                  -> Most likely the first revision, unless
                             your history is very long.
before:

Supply any revision spec to return the parent of that revision. This is mostly useful when inspecting revisions that are not in the revision history of a branch.

It is an error to request the parent of the null revision (before:0).

Examples:

before:1913    -> Return the parent of revno 1913 (revno 1912)
before:revid:aaaa@bbbb-1234567890  -> return the parent of revision
                                      aaaa@bbbb-1234567890
bzr diff -r before:1913..1913
      -> Find the changes between revision 1913 and its parent (1912).
         (What changes did revision 1913 introduce).
         This is equivalent to:  bzr diff -c 1913
last:

Supply a positive number to get the nth revision from the end. This is the same as supplying negative numbers to the 'revno:' spec. Examples:

last:1        -> return the last revision
last:3        -> return the revision 2 before the end.

Standard Options

Standard options are legal for all commands.

--help, -h Show help message.
--verbose, -v Display more information.
--quiet, -q Only display errors and warnings.

Unlike global options, standard options can be used in aliases.

Status Flags

Status flags are used to summarise changes to the working tree in a concise manner. They are in the form:

xxx   <filename>

where the columns' meanings are as follows.

Column 1 - versioning/renames:

+ File versioned
- File unversioned
R File renamed
? File unknown
X File nonexistent (and unknown to bzr)
C File has conflicts
P Entry for a pending merge (not a file)

Column 2 - contents:

N File created
D File deleted
K File kind changed
M File modified

Column 3 - execute:

* The execute bit was changed

URL Identifiers

Supported URL prefixes:

aftp://             Access using active FTP.
bzr://              Fast access using the Bazaar smart server.
bzr+ssh://          Fast access using the Bazaar smart server over SSH.
file://             Access using the standard filesystem (default)
ftp://              Access using passive FTP.
http://             Read-only access of branches exported on the web.
https://            Read-only access of branches exported on the web using SSL.
sftp://             Access using SFTP (most SSH servers provide SFTP).

Commands

add

Purpose:

Add specified files or directories.

Usage:

bzr add [FILE...]

Options:
--dry-run

Show what would be done, but don't actually do anything.

-v, --verbose

Display more information.

--file-ids-from=ARG
 

Lookup file ids from this tree.

--no-recurse

Don't recursively add the contents of directories.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

-h, --help

Show help message.

Description:

In non-recursive mode, all the named items are added, regardless of whether they were previously ignored. A warning is given if any of the named files are already versioned.

In recursive mode (the default), files are treated the same way but the behaviour for directories is different. Directories that are already versioned do not give a warning. All directories, whether already versioned or not, are searched for files or subdirectories that are neither versioned or ignored, and these are added. This search proceeds recursively into versioned directories. If no names are given '.' is assumed.

Therefore simply saying 'bzr add' will version all files that are currently unknown.

Adding a file whose parent directory is not versioned will implicitly add the parent, and so on up to the root. This means you should never need to explicitly add a directory, they'll just get added when you add a file in the directory.

--dry-run will show which files would be added, but not actually add them.

--file-ids-from will try to use the file ids from the supplied path. It looks up ids trying to find a matching parent directory with the same filename, and then by pure path. This option is rarely needed but can be useful when adding the same logical file into two branches that will be merged later (without showing the two different adds as a conflict). It is also useful when merging another project into a subdirectory of this one.

See also:

remove

alias

Purpose:

Set/unset and display aliases.

Usage:

bzr alias [NAME]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--remove

Remove the alias.

-h, --help

Show help message.

Examples:

Show the current aliases:

bzr alias

Show the alias specified for 'll':

bzr alias ll

Set an alias for 'll':

bzr alias ll="log --line -r-10..-1"

To remove an alias for 'll':

bzr alias --remove ll

annotate

Purpose:

Show the origin of each line in a file.

Usage:

bzr annotate FILENAME

Options:
--all

Show annotations on all lines.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--long

Show commit date in annotations.

--usage

Show usage message and options.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-h, --help

Show help message.

Description:

This prints out the given file with an annotation on the left side indicating which revision, author and date introduced the change.

If the origin is the same for a run of consecutive lines, it is shown only at the top, unless the --all option is given.

Aliases:

ann, blame, praise

bind

Purpose:

Convert the current branch into a checkout of the supplied branch.

Usage:

bzr bind [LOCATION]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

Once converted into a checkout, commits must succeed on the master branch before they will be applied to the local branch.

Bound branches use the nickname of its master branch unless it is set locally, in which case binding will update the the local nickname to be that of the master.

See also:

checkouts, unbind

branch

Purpose:

Create a new branch that is a copy of an existing branch.

Usage:

bzr branch FROM_LOCATION [TO_LOCATION]

Options:
--use-existing-dir
 

By default branch will fail if the target directory exists, but does not already have a control directory. This flag will allow branch to proceed.

--stacked

Create a stacked branch referring to the source branch. The new branch will depend on the availability of the source branch for all operations.

-v, --verbose

Display more information.

--standalone

Do not use a shared repository, even if available.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--hardlink

Hard-link working tree files where possible.

--usage

Show usage message and options.

--no-tree

Create a branch without a working-tree.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

If the TO_LOCATION is omitted, the last component of the FROM_LOCATION will be used. In other words, "branch ../foo/bar" will attempt to create ./bar. If the FROM_LOCATION has no / or path separator embedded, the TO_LOCATION is derived from the FROM_LOCATION by stripping a leading scheme or drive identifier, if any. For example, "branch lp:foo-bar" will attempt to create ./foo-bar.

To retrieve the branch as of a particular revision, supply the --revision parameter, as in "branch foo/bar -r 5".

Aliases:

get, clone

See also:

checkout

break-lock

Purpose:

Break a dead lock on a repository, branch or working directory.

Usage:

bzr break-lock [LOCATION]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

CAUTION: Locks should only be broken when you are sure that the process holding the lock has been stopped.

You can get information on what locks are open via the 'bzr info' command.

Examples:

bzr break-lock

cat

Purpose:

Write the contents of a file as of a given revision to standard output.

Usage:

bzr cat FILENAME

Options:
-v, --verbose

Display more information.

--name-from-revision
 

The path name in the old tree.

-q, --quiet

Only display errors and warnings.

--filters

Apply content filters to display the convenience form.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-h, --help

Show help message.

Description:

If no revision is nominated, the last revision is used.

Note: Take care to redirect standard output when using this command on a binary file.

See also:

ls

check

Purpose:

Validate working tree structure, branch consistency and repository history.

Usage:

bzr check [PATH]

Options:
-v, --verbose

Display more information.

--tree

Check the working tree related to the current directory.

-q, --quiet

Only display errors and warnings.

--repo

Check the repository related to the current directory.

--branch

Check the branch related to the current directory.

--usage

Show usage message and options.

-h, --help

Show help message.

Description:

This command checks various invariants about branch and repository storage to detect data corruption or bzr bugs.

The working tree and branch checks will only give output if a problem is detected. The output fields of the repository check are:

revisions

This is just the number of revisions checked. It doesn't indicate a problem.

versionedfiles

This is just the number of versionedfiles checked. It doesn't indicate a problem.

unreferenced ancestors

Texts that are ancestors of other texts, but are not properly referenced by the revision ancestry. This is a subtle problem that Bazaar can work around.

unique file texts

This is the total number of unique file contents seen in the checked revisions. It does not indicate a problem.

repeated file texts

This is the total number of repeated texts seen in the checked revisions. Texts can be repeated when their file entries are modified, but the file contents are not. It does not indicate a problem.

If no restrictions are specified, all Bazaar data that is found at the given location will be checked.

Examples:

Check the tree and branch at 'foo':

bzr check --tree --branch foo

Check only the repository at 'bar':

bzr check --repo bar

Check everything at 'baz':

bzr check baz
See also:

reconcile

checkout

Purpose:

Create a new checkout of an existing branch.

Usage:

bzr checkout [BRANCH_LOCATION] [TO_LOCATION]

Options:
-v, --verbose

Display more information.

--files-from=ARG
 

Get file contents from this tree.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--hardlink

Hard-link working tree files where possible.

--lightweight

Perform a lightweight checkout. Lightweight checkouts depend on access to the branch for every operation. Normal checkouts can perform common operations like diff and status without such access, and also support local commits.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

If BRANCH_LOCATION is omitted, checkout will reconstitute a working tree for the branch found in '.'. This is useful if you have removed the working tree or if it was never created - i.e. if you pushed the branch to its current location using SFTP.

If the TO_LOCATION is omitted, the last component of the BRANCH_LOCATION will be used. In other words, "checkout ../foo/bar" will attempt to create ./bar. If the BRANCH_LOCATION has no / or path separator embedded, the TO_LOCATION is derived from the BRANCH_LOCATION by stripping a leading scheme or drive identifier, if any. For example, "checkout lp:foo-bar" will attempt to create ./foo-bar.

To retrieve the branch as of a particular revision, supply the --revision parameter, as in "checkout foo/bar -r 5". Note that this will be immediately out of date [so you cannot commit] but it may be useful (i.e. to examine old code.)

Aliases:

co

See also:

branch, checkouts

clean-tree

Purpose:

Remove unwanted files from working tree.

Usage:

bzr clean-tree

Options:
--ignored

Delete all ignored files.

--dry-run

Show files to delete instead of deleting them.

-v, --verbose

Display more information.

--unknown

Delete files unknown to bzr (default).

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--force

Do not prompt before deleting.

--detritus

Delete conflict files, merge backups, and failed selftest dirs.

-h, --help

Show help message.

Description:

By default, only unknown files, not ignored files, are deleted. Versioned files are never deleted.

Another class is 'detritus', which includes files emitted by bzr during normal operations and selftests. (The value of these files decreases with time.)

If no options are specified, unknown files are deleted. Otherwise, option flags are respected, and may be combined.

To check what clean-tree will do, use --dry-run.

commit

Purpose:

Commit changes into a new revision.

Usage:

bzr commit [SELECTED...]

Options:
-v, --verbose

Display more information.

--author=ARG

Set the author's name, if it's different from the committer.

--unchanged

Commit even if nothing has changed.

--fixes=ARG

Mark a bug as being fixed by this revision (see "bzr help bugs").

-q, --quiet

Only display errors and warnings.

--show-diff

When no message is supplied, show the diff along with the status summary in the message editor.

--strict

Refuse to commit if there are unknown files in the working tree.

-F MSGFILE, --file=MSGFILE
 

Take commit message from this file.

--usage

Show usage message and options.

-x ARG, --exclude=ARG
 

Do not consider changes made to a given path.

-m ARG, --message=ARG
 

Description of the new revision.

--local

Perform a local commit in a bound branch. Local commits are not pushed to the master branch until a normal commit is performed.

-h, --help

Show help message.

Description:

An explanatory message needs to be given for each commit. This is often done by using the --message option (getting the message from the command line) or by using the --file option (getting the message from a file). If neither of these options is given, an editor is opened for the user to enter the message. To see the changed files in the boilerplate text loaded into the editor, use the --show-diff option.

By default, the entire tree is committed and the person doing the commit is assumed to be the author. These defaults can be overridden as explained below.

Selective commits:
 

If selected files are specified, only changes to those files are committed. If a directory is specified then the directory and everything within it is committed.

When excludes are given, they take precedence over selected files. For example, to commit only changes within foo, but not changes within foo/bar:

bzr commit foo -x foo/bar

A selective commit after a merge is not yet supported.

Custom authors:

If the author of the change is not the same person as the committer, you can specify the author's name using the --author option. The name should be in the same format as a committer-id, e.g. "John Doe <jdoe@example.com>". If there is more than one author of the change you can specify the option multiple times, once for each author.

Checks:

A common mistake is to forget to add a new file or directory before running the commit command. The --strict option checks for unknown files and aborts the commit if any are found. More advanced pre-commit checks can be implemented by defining hooks. See bzr help hooks for details.

Things to note:

If you accidentially commit the wrong changes or make a spelling mistake in the commit message say, you can use the uncommit command to undo it. See bzr help uncommit for details.

Hooks can also be configured to run after a commit. This allows you to trigger updates to external systems like bug trackers. The --fixes option can be used to record the association between a revision and one or more bugs. See bzr help bugs for details.

A selective commit may fail in some cases where the committed tree would be invalid. Consider:

bzr init foo
mkdir foo/bar
bzr add foo/bar
bzr commit foo -m "committing foo"
bzr mv foo/bar foo/baz
mkdir foo/bar
bzr add foo/bar
bzr commit foo/bar -m "committing bar but not baz"

In the example above, the last commit will fail by design. This gives the user the opportunity to decide whether they want to commit the rename at the same time, separately first, or not at all. (As a general rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)

Aliases:

ci, checkin

See also:

add, bugs, hooks, uncommit

conflicts

Purpose:

List files with conflicts.

Usage:

bzr conflicts

Options:
--usage

Show usage message and options.

--text

List paths of files with text conflicts.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

Merge will do its best to combine the changes in two branches, but there are some kinds of problems only a human can fix. When it encounters those, it will mark a conflict. A conflict means that you need to fix something, before you should commit.

Conflicts normally are listed as short, human-readable messages. If --text is supplied, the pathnames of files with text conflicts are listed, instead. (This is useful for editing all files with text conflicts.)

Use bzr resolve when you have fixed a problem.

See also bzr resolve.

deleted

Purpose:

List files deleted in the working tree.

Usage:

bzr deleted

Options:
--usage

Show usage message and options.

--show-ids

Show internal object ids.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

See also:

ls, status

diff

Purpose:

Show differences in the working tree, between revisions or branches.

Usage:

bzr diff [FILE...]

Options:
--old=ARG

Branch/tree to compare from.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-p ARG, --prefix=ARG
 

Set prefixes added to old and new filenames, as two values separated by a colon. (eg "old/:new/").

--using=ARG

Use this command to compare files.

--usage

Show usage message and options.

--new=ARG

Branch/tree to compare to.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--diff-options=ARG
 

Pass these options to the external diff program.

-c ARG, --change=ARG
 

Select changes introduced by the specified revision. See also "help revisionspec".

-h, --help

Show help message.

Description:

If no arguments are given, all changes for the current tree are listed. If files are given, only the changes in those files are listed. Remote and multiple branches can be compared by using the --old and --new options. If not provided, the default for both is derived from the first argument, if any, or the current tree if no arguments are given.

"bzr diff -p1" is equivalent to "bzr diff --prefix old/:new/", and produces patches suitable for "patch -p1".

Exit values:

1 - changed 2 - unrepresentable changes 3 - error 0 - no change

Examples:

Shows the difference in the working tree versus the last commit:

bzr diff

Difference between the working tree and revision 1:

bzr diff -r1

Difference between revision 2 and revision 1:

bzr diff -r1..2

Difference between revision 2 and revision 1 for branch xxx:

bzr diff -r1..2 xxx

Show just the differences for file NEWS:

bzr diff NEWS

Show the differences in working tree xxx for file NEWS:

bzr diff xxx/NEWS

Show the differences from branch xxx to this working tree:

bzr diff --old xxx

Show the differences between two branches for file NEWS:

bzr diff --old xxx --new yyy NEWS

Same as 'bzr diff' but prefix paths with old/ and new/:

bzr diff --prefix old/:new/
Aliases:

di, dif

See also:

status

export

Purpose:

Export current or past revision to a destination directory or archive.

Usage:

bzr export DEST [BRANCH_OR_SUBDIR]

Options:
-v, --verbose

Display more information.

--format=ARG

Type of file to export to.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--filters

Apply content filters to export the convenient form.

--usage

Show usage message and options.

--root=ARG

Name of the root directory inside the exported file.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

If no revision is specified this exports the last committed revision.

Format may be an "exporter" name, such as tar, tgz, tbz2. If none is given, try to find the format with the extension. If no extension is found exports to a directory (equivalent to --format=dir).

If root is supplied, it will be used as the root directory inside container formats (tar, zip, etc). If it is not supplied it will default to the exported filename. The root option has no effect for 'dir' format.

If branch is omitted then the branch containing the current working directory will be used.

Note: Export of tree with non-ASCII filenames to zip is not supported.

Supported formats

Autodetected by extension

dir

(none)

tar

.tar

tbz2

.tar.bz2, .tbz2

tgz

.tar.gz, .tgz

zip

.zip

help

Purpose:

Show help on a command or other topic.

Usage:

bzr help [TOPIC]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--long

Show help on all commands.

-h, --help

Show help message.

Aliases:

?, --help, -?, -h

See also:

topics

ignore

Purpose:

Ignore specified files or patterns.

Usage:

bzr ignore [NAME_PATTERN...]

Options:
--usage

Show usage message and options.

--old-default-rules
 

Write out the ignore rules bzr < 0.9 always used.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

See bzr help patterns for details on the syntax of patterns.

To remove patterns from the ignore list, edit the .bzrignore file. After adding, editing or deleting that file either indirectly by using this command or directly by using an editor, be sure to commit it.

Note: ignore patterns containing shell wildcards must be quoted from the shell on Unix.

Examples:

Ignore the top level Makefile:

bzr ignore ./Makefile

Ignore class files in all directories:

bzr ignore "*.class"

Ignore .o files under the lib directory:

bzr ignore "lib/**/*.o"

Ignore .o files under the lib directory:

bzr ignore "RE:lib/.*\.o"

Ignore everything but the "debian" toplevel directory:

bzr ignore "RE:(?!debian/).*"
See also:

ignored, patterns, status

ignored

Purpose:

List ignored files and the patterns that matched them.

Usage:

bzr ignored

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

List all the ignored files and the ignore pattern that caused the file to be ignored.

Alternatively, to list just the files:

bzr ls --ignored
See also:

ignore, ls

info

Purpose:

Show information about a working tree, branch or repository.

Usage:

bzr info [LOCATION]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This command will show all known locations and formats associated to the tree, branch or repository.

In verbose mode, statistical information is included with each report. To see extended statistic information, use a verbosity level of 2 or higher by specifying the verbose option multiple times, e.g. -vv.

Branches and working trees will also report any missing revisions.

Examples:

Display information on the format and related locations:

bzr info

Display the above together with extended format information and basic statistics (like the number of files in the working tree and number of revisions in the branch and repository):

bzr info -v

Display the above together with number of committers to the branch:

bzr info -vv

See also:

repositories, revno, working-trees

init

Purpose:

Make a directory into a versioned branch.

Usage:

bzr init [LOCATION]

Options:
-v, --verbose

Display more information.

--create-prefix
 

Create the path leading up to the branch if it does not already exist.

-q, --quiet

Only display errors and warnings.

--append-revisions-only
 

Never change revnos or the existing log. Append revisions to it only.

--usage

Show usage message and options.

-h, --help

Show help message.

Branch Format:
--format=ARG

Specify a format for this branch. See "help formats".

--1.14

A working-tree format that supports content filtering.

--1.14-rich-root
 

A variant of 1.14 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.6

A format that allows a branch to indicate that there is another (stacked) repository that should be used to access data that is not present locally.

--1.6.1-rich-root
 

A variant of 1.6 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.9

A repository format using B+tree indexes. These indexes are smaller in size, have smarter caching and provide faster performance for most operations.

--1.9-rich-root
 

A variant of 1.9 that supports rich-root data (needed for bzr-svn and bzr-git).

--2a

First format for bzr 2.0 series. Uses group-compress storage. Provides rich roots which are a one-way transition.

--default

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--default-rich-root
 

Default format, rich root variant. (needed for bzr-svn and bzr-git).

--development-rich-root
 

Current development format. Supports rich roots. Can convert data to and from rich-root-pack (and anything compatible with rich-root-pack) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc.bazaar- vcs.org/latest/developers/development-repo.html before use.

--development-subtree
 

Current development format, subtree variant. Can convert data to and from pack-0.92-subtree (and anything compatible with pack-0.92-subtree) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc .bazaar-vcs.org/latest/developers/development- repo.html before use.

--dirstate

New in 0.15: Fast local operations. Compatible with bzr 0.8 and above when accessed over the network.

--dirstate-tags
 

New in 0.15: Fast local operations and improved scaling for network operations. Additionally adds support for tags. Incompatible with bzr < 0.15.

--knit

Format using knits. Recommended for interoperation with bzr <= 0.14.

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--rich-root

New in 1.0. Better handling of tree roots. Incompatible with bzr < 1.0.

--rich-root-pack
 

New in 1.0: A variant of pack-0.92 that supports rich- root data (needed for bzr-svn and bzr-git).

--weave

Pre-0.8 format. Slower than knit and does not support checkouts or shared repositories.

Description:

Use this to create an empty branch, or before importing an existing project.

If there is a repository in a parent directory of the location, then the history of the branch will be stored in the repository. Otherwise init creates a standalone branch which carries its own history in the .bzr directory.

If there is already a branch at the location but it has no working tree, the tree can be populated with 'bzr checkout'.

Recipe for importing a tree of files:

cd ~/project
bzr init
bzr add .
bzr status
bzr commit -m "imported project"
See also:

branch, checkout, init-repository

init-repository

Purpose:

Create a shared repository to hold branches.

Usage:

bzr init-repository LOCATION

Options:
--no-trees

Branches in the repository will default to not having a working tree.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

-h, --help

Show help message.

Repository format:
--format=ARG

Specify a format for this repository. See "bzr help formats" for details.

--1.14

A working-tree format that supports content filtering.

--1.14-rich-root
 

A variant of 1.14 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.6

A format that allows a branch to indicate that there is another (stacked) repository that should be used to access data that is not present locally.

--1.6.1-rich-root
 

A variant of 1.6 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.9

A repository format using B+tree indexes. These indexes are smaller in size, have smarter caching and provide faster performance for most operations.

--1.9-rich-root
 

A variant of 1.9 that supports rich-root data (needed for bzr-svn and bzr-git).

--2a

First format for bzr 2.0 series. Uses group-compress storage. Provides rich roots which are a one-way transition.

--default

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--default-rich-root
 

Default format, rich root variant. (needed for bzr-svn and bzr-git).

--development-rich-root
 

Current development format. Supports rich roots. Can convert data to and from rich-root-pack (and anything compatible with rich-root-pack) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc.bazaar- vcs.org/latest/developers/development-repo.html before use.

--development-subtree
 

Current development format, subtree variant. Can convert data to and from pack-0.92-subtree (and anything compatible with pack-0.92-subtree) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc .bazaar-vcs.org/latest/developers/development- repo.html before use.

--dirstate

New in 0.15: Fast local operations. Compatible with bzr 0.8 and above when accessed over the network.

--dirstate-tags
 

New in 0.15: Fast local operations and improved scaling for network operations. Additionally adds support for tags. Incompatible with bzr < 0.15.

--knit

Format using knits. Recommended for interoperation with bzr <= 0.14.

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--rich-root

New in 1.0. Better handling of tree roots. Incompatible with bzr < 1.0.

--rich-root-pack
 

New in 1.0: A variant of pack-0.92 that supports rich- root data (needed for bzr-svn and bzr-git).

--weave

Pre-0.8 format. Slower than knit and does not support checkouts or shared repositories.

Description:

New branches created under the repository directory will store their revisions in the repository, not in the branch directory.

If the --no-trees option is used then the branches in the repository will not have working trees by default.

Examples:

Create a shared repositories holding just branches:

bzr init-repo --no-trees repo
bzr init repo/trunk

Make a lightweight checkout elsewhere:

bzr checkout --lightweight repo/trunk trunk-checkout
cd trunk-checkout
(add files here)
Aliases:

init-repo

See also:

branch, checkout, init, repositories

join

Purpose:

Combine a tree into its containing tree.

Usage:

bzr join TREE

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This command requires the target tree to be in a rich-root format.

The TREE argument should be an independent tree, inside another tree, but not part of it. (Such trees can be produced by "bzr split", but also by running "bzr branch" with the target inside a tree.)

The result is a combined tree, with the subtree no longer an independant part. This is marked as a merge of the subtree into the containing tree, and all history is preserved.

See also:

split

log

Purpose:

Show historical log for a branch or subset of a branch.

Usage:

bzr log [FILE...]

Options:
-v, --verbose

Show files changed in each revision.

-q, --quiet

Only display errors and warnings.

--include-merges
 

Show merged revisions like --levels 0 does.

-p, --show-diff
 

Show changes made in each revision as a patch.

--forward

Show from oldest to newest.

-n N, --levels=N
 

Number of levels to display - 0 for all, 1 for flat.

-l N, --limit=N
 

Limit the output to the first N revisions.

--usage

Show usage message and options.

--timezone=ARG

Display timezone as local, original, or utc.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-m ARG, --message=ARG
 

Show revisions whose message matches this regular expression.

-c ARG, --change=ARG
 

Show just the specified revision. See also "help revisionspec".

-h, --help

Show help message.

Log format:
--log-format=ARG
 

Use specified log format.

--gnu-changelog
 

Format used by GNU ChangeLog files

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

log is bzr's default tool for exploring the history of a branch. The branch to use is taken from the first parameter. If no parameters are given, the branch containing the working directory is logged. Here are some simple examples:

bzr log                       log the current branch
bzr log foo.py                log a file in its branch
bzr log http://server/branch  log a branch on a server

The filtering, ordering and information shown for each revision can be controlled as explained below. By default, all revisions are shown sorted (topologically) so that newer revisions appear before older ones and descendants always appear before ancestors. If displayed, merged revisions are shown indented under the revision in which they were merged.

Output control:

The log format controls how information about each revision is displayed. The standard log formats are called long, short and line. The default is long. See bzr help log-formats for more details on log formats.

The following options can be used to control what information is displayed:

-l N        display a maximum of N revisions
-n N        display N levels of revisions (0 for all, 1 for collapsed)
-v          display a status summary (delta) for each revision
-p          display a diff (patch) for each revision
--show-ids  display revision-ids (and file-ids), not just revnos

Note that the default number of levels to display is a function of the log format. If the -n option is not used, the standard log formats show just the top level (mainline).

Status summaries are shown using status flags like A, M, etc. To see the changes explained using words like added and modified instead, use the -vv option.

Ordering control:
 

To display revisions from oldest to newest, use the --forward option. In most cases, using this option will have little impact on the total time taken to produce a log, though --forward does not incrementally display revisions like --reverse does when it can.

Revision filtering:
 

The -r option can be used to specify what revision or range of revisions to filter against. The various forms are shown below:

-rX      display revision X
-rX..    display revision X and later
-r..Y    display up to and including revision Y
-rX..Y   display from X to Y inclusive

See bzr help revisionspec for details on how to specify X and Y. Some common examples are given below:

-r-1                show just the tip
-r-10..             show the last 10 mainline revisions
-rsubmit:..         show what's new on this branch
-rancestor:path..   show changes since the common ancestor of this
                    branch and the one at location path
-rdate:yesterday..  show changes since yesterday

When logging a range of revisions using -rX..Y, log starts at revision Y and searches back in history through the primary ("left-hand") parents until it finds X. When logging just the top level (using -n1), an error is reported if X is not found along the way. If multi-level logging is used (-n0), X may be a nested merge revision and the log will be truncated accordingly.

Path filtering:

If parameters are given and the first one is not a branch, the log will be filtered to show only those revisions that changed the nominated files or directories.

Filenames are interpreted within their historical context. To log a deleted file, specify a revision range so that the file existed at the end or start of the range.

Historical context is also important when interpreting pathnames of renamed files/directories. Consider the following example:

  • revision 1: add tutorial.txt
  • revision 2: modify tutorial.txt
  • revision 3: rename tutorial.txt to guide.txt; add tutorial.txt

In this case:

  • bzr log guide.txt will log the file added in revision 1
  • bzr log tutorial.txt will log the new file added in revision 3
  • bzr log -r2 -p tutorial.txt will show the changes made to the original file in revision 2.
  • bzr log -r2 -p guide.txt will display an error message as there was no file called guide.txt in revision 2.

Renames are always followed by log. By design, there is no need to explicitly ask for this (and no way to stop logging a file back until it was last renamed).

Other filtering:
 

The --message option can be used for finding revisions that match a regular expression in a commit message.

Tips & tricks:

GUI tools and IDEs are often better at exploring history than command line tools. You may prefer qlog or glog from the QBzr and Bzr-Gtk packages respectively for example. (TortoiseBzr uses qlog for displaying logs.) See http://bazaar-vcs.org/BzrPlugins and http://bazaar-vcs.org/IDEIntegration.

Web interfaces are often better at exploring history than command line tools, particularly for branches on servers. You may prefer Loggerhead or one of its alternatives. See http://bazaar-vcs.org/WebInterface.

You may find it useful to add the aliases below to bazaar.conf:

[ALIASES]
tip = log -r-1
top = log -l10 --line
show = log -v -p

bzr tip will then show the latest revision while bzr top will show the last 10 mainline revisions. To see the details of a particular revision X, bzr show -rX.

If you are interested in looking deeper into a particular merge X, use bzr log -n0 -rX.

bzr log -v on a branch with lots of history is currently very slow. A fix for this issue is currently under development. With or without that fix, it is recommended that a revision range be given when using the -v option.

bzr has a generic full-text matching plugin, bzr-search, that can be used to find revisions matching user names, commit messages, etc. Among other features, this plugin can find all revisions containing a list of words but not others.

When exploring non-mainline history on large projects with deep history, the performance of log can be greatly improved by installing the historycache plugin. This plugin buffers historical information trading disk space for faster speed.

See also:

log-formats, revisionspec

ls

Purpose:

List files in a tree.

Usage:

bzr ls [PATH]

Options:
--from-root

Print paths relative to the root of the branch.

--ignored

Print ignored files.

--kind=ARG

List entries of a particular kind: file, directory, symlink.

-v, --verbose

Display more information.

-R, --recursive
 

Recurse into subdirectories.

-V, --versioned
 

Print versioned files.

--unknown

Print unknown files.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--show-ids

Show internal object ids.

--null

Write an ascii NUL (0) separator between files rather than a newline.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

See also:

cat, status

merge

Purpose:

Perform a three-way merge.

Usage:

bzr merge [LOCATION]

Options:
--pull

If the destination is already completely merged into the source, pull from the source rather than merging. When this happens, you do not need to commit the result.

--remember

Remember the specified location as a default.

--force

Merge even if the destination tree has uncommitted changes.

-v, --verbose

Display more information.

--reprocess

Reprocess to reduce spurious conflicts.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch to merge into, rather than the one containing the working directory.

--uncommitted

Apply uncommitted changes from a working copy, instead of branch changes.

--usage

Show usage message and options.

--show-base

Show base revision text in conflicts.

--preview

Instead of merging, show a diff of the merge.

-c ARG, --change=ARG
 

Select changes introduced by the specified revision. See also "help revisionspec".

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Merge algorithm:
--merge-type=ARG
 

Select a particular merge algorithm.

--diff3

Merge using external diff3

--lca

LCA-newness merge

--merge3

Native diff3-style merge

--weave

Weave-based merge

Description:

The source of the merge can be specified either in the form of a branch, or in the form of a path to a file containing a merge directive generated with bzr send. If neither is specified, the default is the upstream branch or the branch most recently merged using --remember.

When merging a branch, by default the tip will be merged. To pick a different revision, pass --revision. If you specify two values, the first will be used as BASE and the second one as OTHER. Merging individual revisions, or a subset of available revisions, like this is commonly referred to as "cherrypicking".

Revision numbers are always relative to the branch being merged.

By default, bzr will try to merge in all new work from the other branch, automatically determining an appropriate base. If this fails, you may need to give an explicit base.

Merge will do its best to combine the changes in two branches, but there are some kinds of problems only a human can fix. When it encounters those, it will mark a conflict. A conflict means that you need to fix something, before you should commit.

Use bzr resolve when you have fixed a problem. See also bzr conflicts.

If there is no default branch set, the first merge will set it. After that, you can omit the branch to use the default. To change the default, use --remember. The value will only be saved if the remote location can be accessed.

The results of the merge are placed into the destination working directory, where they can be reviewed (with bzr diff), tested, and then committed to record the result of the merge.

merge refuses to run if there are any uncommitted changes, unless --force is given.

Examples:

To merge the latest revision from bzr.dev:

bzr merge ../bzr.dev

To merge changes up to and including revision 82 from bzr.dev:

bzr merge -r 82 ../bzr.dev

To merge the changes introduced by 82, without previous changes:

bzr merge -r 81..82 ../bzr.dev

To apply a merge directive contained in /tmp/merge:

bzr merge /tmp/merge

See also:

remerge, send, status-flags, update

missing

Purpose:

Show unmerged/unpulled revisions between two branches.

Usage:

bzr missing [OTHER_BRANCH]

Options:
--reverse

Reverse the order of revisions.

--this

Same as --mine-only.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--other

Same as --theirs-only.

--include-merges
 

Show all revisions in addition to the mainline ones.

--mine-only

Display changes in the local branch only.

--usage

Show usage message and options.

--my-revision=ARG
 

Filter on local branch revisions (inclusive). See "help revisionspec" for details.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

Filter on other branch revisions (inclusive). See "help revisionspec" for details.

--theirs-only

Display changes in the remote branch only.

-v, --verbose

Display more information.

Log format:
--log-format=ARG
 

Use specified log format.

--gnu-changelog
 

Format used by GNU ChangeLog files

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

OTHER_BRANCH may be local or remote.

To filter on a range of revisions, you can use the command -r begin..end -r revision requests a specific revision, -r ..end or -r begin.. are also valid.

Examples:

Determine the missing revisions between this and the branch at the remembered pull location:

bzr missing

Determine the missing revisions between this and another branch:

bzr missing http://server/branch

Determine the missing revisions up to a specific revision on the other branch:

bzr missing -r ..-10

Determine the missing revisions up to a specific revision on this branch:

bzr missing --my-revision ..-10
See also:

merge, pull

mkdir

Purpose:

Create a new versioned directory.

Usage:

bzr mkdir DIR...

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This is equivalent to creating the directory and then adding it.

mv

Purpose:

Move or rename a file.

Usage:

bzr mv OLDNAME NEWNAME

bzr mv SOURCE... DESTINATION

Options:
--dry-run

Avoid making changes when guessing renames.

-v, --verbose

Display more information.

--auto

Automatically guess renames.

--after

Move only the bzr identifier of the file, because the file has already been moved.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

-h, --help

Show help message.

Description:

If the last argument is a versioned directory, all the other names are moved into it. Otherwise, there must be exactly two arguments and the file is changed to a new name.

If OLDNAME does not exist on the filesystem but is versioned and NEWNAME does exist on the filesystem but is not versioned, mv assumes that the file has been manually moved and only updates its internal inventory to reflect that change. The same is valid when moving many SOURCE files to a DESTINATION.

Files cannot be moved between branches.

Aliases:

move, rename

nick

Purpose:

Print or set the branch nickname.

Usage:

bzr nick [NICKNAME]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

If unset, the tree root directory name is used as the nickname. To print the current nickname, execute with no argument.

Bound branches use the nickname of its master branch unless it is set locally.

See also:

info

pack

Purpose:

Compress the data within a repository.

Usage:

bzr pack [BRANCH_OR_REPO]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

See also:

repositories

plugins

Purpose:

List the installed plugins.

Usage:

bzr plugins

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This command displays the list of installed plugins including version of plugin and a short description of each.

--verbose shows the path where each plugin is located.

A plugin is an external component for Bazaar that extends the revision control system, by adding or replacing code in Bazaar. Plugins can do a variety of things, including overriding commands, adding new commands, providing additional network transports and customizing log output.

See the Bazaar web site, http://bazaar-vcs.org, for further information on plugins including where to find them and how to install them. Instructions are also provided there on how to write new plugins using the Python programming language.

pull

Purpose:

Turn this branch into a mirror of another branch.

Usage:

bzr pull [LOCATION]

Options:
--remember

Remember the specified location as a default.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch to pull into, rather than the one containing the working directory.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--local

Perform a local pull in a bound branch. Local pulls are not applied to the master branch.

--overwrite

Ignore differences between branches and overwrite unconditionally.

-v, --verbose

Show logs of pulled revisions.

Description:

This command only works on branches that have not diverged. Branches are considered diverged if the destination branch's most recent commit is one that has not been merged (directly or indirectly) into the parent.

If branches have diverged, you can use 'bzr merge' to integrate the changes from one into the other. Once one branch has merged, the other should be able to pull it again.

If you want to forget your local changes and just update your branch to match the remote one, use pull --overwrite.

If there is no default location set, the first pull will set it. After that, you can omit the location to use the default. To change the default, use --remember. The value will only be saved if the remote location can be accessed.

Note: The location can be specified either in the form of a branch, or in the form of a path to a file containing a merge directive generated with bzr send.

See also:

push, send, status-flags, update

push

Purpose:

Update a mirror of this branch.

Usage:

bzr push [LOCATION]

Options:
--stacked

Create a stacked branch that references the public location of the parent branch.

--remember

Remember the specified location as a default.

--strict

Refuse to push if there are uncommitted changes in the working tree, --no-strict disables the check.

--create-prefix
 

Create the path leading up to the branch if it does not already exist.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--stacked-on=ARG
 

Create a stacked branch that refers to another branch for the commit history. Only the work not present in the referenced branch is included in the branch created.

-d ARG, --directory=ARG
 

Branch to push from, rather than the one containing the working directory.

--use-existing-dir
 

By default push will fail if the target directory exists, but does not already have a control directory. This flag will allow push to proceed.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--overwrite

Ignore differences between branches and overwrite unconditionally.

-v, --verbose

Display more information.

Description:

The target branch will not have its working tree populated because this is both expensive, and is not supported on remote file systems.

Some smart servers or protocols may put the working tree in place in the future.

This command only works on branches that have not diverged. Branches are considered diverged if the destination branch's most recent commit is one that has not been merged (directly or indirectly) by the source branch.

If branches have diverged, you can use 'bzr push --overwrite' to replace the other branch completely, discarding its unmerged changes.

If you want to ensure you have the different changes in the other branch, do a merge (see bzr help merge) from the other branch, and commit that. After that you will be able to do a push without '--overwrite'.

If there is no default push location set, the first push will set it. After that, you can omit the location to use the default. To change the default, use --remember. The value will only be saved if the remote location can be accessed.

See also:

pull, update, working-trees

reconcile

Purpose:

Reconcile bzr metadata in a branch.

Usage:

bzr reconcile [BRANCH]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This can correct data mismatches that may have been caused by previous ghost operations or bzr upgrades. You should only need to run this command if 'bzr check' or a bzr developer advises you to run it.

If a second branch is provided, cross-branch reconciliation is also attempted, which will check that data like the tree root id which was not present in very early bzr versions is represented correctly in both branches.

At the same time it is run it may recompress data resulting in a potential saving in disk space or performance gain.

The branch MUST be on a listable system such as local disk or sftp.

See also:

check

reconfigure

Purpose:

Reconfigure the type of a bzr directory.

Usage:

bzr reconfigure [LOCATION]

Options:
--force

Perform reconfiguration even if local changes will be lost.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--bind-to=ARG

Branch to bind checkout to.

--usage

Show usage message and options.

-h, --help

Show help message.

Target type:
--branch

Reconfigure to be an unbound branch with no working tree.

--checkout

Reconfigure to be a bound branch with a working tree.

--lightweight-checkout
 

Reconfigure to be a lightweight checkout (with no local history).

--standalone

Reconfigure to be a standalone branch (i.e. stop using shared repository).

--tree

Reconfigure to be an unbound branch with a working tree.

--use-shared

Reconfigure to use a shared repository.

--with-no-trees
 

Reconfigure repository to not create working trees on branches by default.

--with-trees

Reconfigure repository to create working trees on branches by default.

Description:

A target configuration must be specified.

For checkouts, the bind-to location will be auto-detected if not specified. The order of preference is 1. For a lightweight checkout, the current bound location. 2. For branches that used to be checkouts, the previously-bound location. 3. The push location. 4. The parent location. If none of these is available, --bind-to must be specified.

See also:

branches, checkouts, standalone-trees, working-trees

remerge

Purpose:

Redo a merge.

Usage:

bzr remerge [FILE...]

Options:
-v, --verbose

Display more information.

--reprocess

Reprocess to reduce spurious conflicts.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--show-base

Show base revision text in conflicts.

-h, --help

Show help message.

Merge algorithm:
--merge-type=ARG
 

Select a particular merge algorithm.

--diff3

Merge using external diff3

--lca

LCA-newness merge

--merge3

Native diff3-style merge

--weave

Weave-based merge

Description:

Use this if you want to try a different merge technique while resolving conflicts. Some merge techniques are better than others, and remerge lets you try different ones on different files.

The options for remerge have the same meaning and defaults as the ones for merge. The difference is that remerge can (only) be run when there is a pending merge, and it lets you specify particular files.

Examples:

Re-do the merge of all conflicted files, and show the base text in conflict regions, in addition to the usual THIS and OTHER texts:

bzr remerge --show-base

Re-do the merge of "foobar", using the weave merge algorithm, with additional processing to reduce the size of conflict regions:

bzr remerge --merge-type weave --reprocess foobar

remove

Purpose:

Remove files or directories.

Usage:

bzr remove [FILE...]

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--new

Only remove files that have never been committed.

-h, --help

Show help message.

Deletion Strategy:
--force

Delete all the specified files, even if they can not be recovered and even if they are non-empty directories.

--keep

Don't delete any files.

--safe

Only delete files if they can be safely recovered (default).

Description:

This makes bzr stop tracking changes to the specified files. bzr will delete them if they can easily be recovered using revert. If no options or parameters are given bzr will scan for files that are being tracked by bzr but missing in your tree and stop tracking them for you.

Aliases:

rm, del

remove-tree

Purpose:

Remove the working tree from a given branch/checkout.

Usage:

bzr remove-tree [LOCATION]

Options:
--usage

Show usage message and options.

--force

Remove the working tree even if it has uncommitted changes.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

Since a lightweight checkout is little more than a working tree this will refuse to run against one.

To re-create the working tree, use "bzr checkout".

See also:

checkout, working-trees

renames

Purpose:

Show list of renamed files.

Usage:

bzr renames [DIR]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

See also:

status

resolve

Purpose:

Mark a conflict as resolved.

Usage:

bzr resolve [FILE...]

Options:
--usage

Show usage message and options.

--all

Resolve all conflicts in this tree.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

Merge will do its best to combine the changes in two branches, but there are some kinds of problems only a human can fix. When it encounters those, it will mark a conflict. A conflict means that you need to fix something, before you should commit.

Once you have fixed a problem, use "bzr resolve" to automatically mark text conflicts as fixed, resolve FILE to mark a specific conflict as resolved, or "bzr resolve --all" to mark all conflicts as resolved.

See also bzr conflicts.

Aliases:

resolved

revert

Purpose:

Revert files to a previous revision.

Usage:

bzr revert [FILE...]

Options:
-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--forget-merges
 

Remove pending merge marker, without changing any files.

--usage

Show usage message and options.

--no-backup

Do not save backups of reverted files.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

Giving a list of files will revert only those files. Otherwise, all files will be reverted. If the revision is not specified with '--revision', the last committed revision is used.

To remove only some changes, without reverting to a prior version, use merge instead. For example, "merge . --revision -2..-3" will remove the changes introduced by -2, without affecting the changes introduced by -1. Or to remove certain changes on a hunk-by-hunk basis, see the Shelf plugin.

By default, any files that have been manually changed will be backed up first. (Files changed only by merge are not backed up.) Backup files have '.~#~' appended to their name, where # is a number.

When you provide files, you can use their current pathname or the pathname from the target revision. So you can use revert to "undelete" a file by name. If you name a directory, all the contents of that directory will be reverted.

Any files that have been newly added since that revision will be deleted, with a backup kept if appropriate. Directories containing unknown files will not be deleted.

The working tree contains a list of pending merged revisions, which will be included as parents in the next commit. Normally, revert clears that list as well as reverting the files. If any files are specified, revert leaves the pending merge list alone and reverts only the files. Use "bzr revert ." in the tree root to revert all files but keep the merge record, and "bzr revert --forget-merges" to clear the pending merge list without reverting any files.

See also:

cat, export

revno

Purpose:

Show current revision number.

Usage:

bzr revno [LOCATION]

Options:
--usage

Show usage message and options.

--tree

Show revno of working tree

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This is equal to the number of revisions on this branch.

See also:

info

root

Purpose:

Show the tree root directory.

Usage:

bzr root [FILENAME]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

The root is the nearest enclosing directory with a .bzr control directory.

send

Purpose:

Mail or create a merge-directive for submitting changes.

Usage:

bzr send [SUBMIT_BRANCH] [PUBLIC_BRANCH]

Options:
--body=ARG

Body for the email.

--remember

Remember submit and public branch.

-f ARG, --from=ARG
 

Branch to generate the submission from, rather than the one containing the working directory.

-v, --verbose

Display more information.

--mail-to=ARG

Mail the request to this address.

--format=ARG

Use the specified output format.

--no-bundle

Do not include a bundle in the merge directive.

-q, --quiet

Only display errors and warnings.

--strict

Refuse to send if there are uncommitted changes in the working tree, --no-strict disables the check.

--usage

Show usage message and options.

-o ARG, --output=ARG
 

Write merge directive to this file; use - for stdout.

-m ARG, --message=ARG
 

Message string.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--no-patch

Do not include a preview patch in the merge directive.

-h, --help

Show help message.

Description:

A merge directive provides many things needed for requesting merges:

  • A machine-readable description of the merge to perform
  • An optional patch that is a preview of the changes requested
  • An optional bundle of revision data, so that the changes can be applied directly from the merge directive, without retrieving data from a branch.

If --no-bundle is specified, then public_branch is needed (and must be up-to-date), so that the receiver can perform the merge using the public_branch. The public_branch is always included if known, so that people can check it later.

The submit branch defaults to the parent, but can be overridden. Both submit branch and public branch will be remembered if supplied.

If a public_branch is known for the submit_branch, that public submit branch is used in the merge instructions. This means that a local mirror can be used as your actual submit branch, once you have set public_branch for that mirror.

Mail is sent using your preferred mail program. This should be transparent on Windows (it uses MAPI). On Linux, it requires the xdg-email utility. If the preferred client can't be found (or used), your editor will be used.

To use a specific mail program, set the mail_client configuration option. (For Thunderbird 1.5, this works around some bugs.) Supported values for specific clients are "claws", "evolution", "kmail", "mutt", and "thunderbird"; generic options are "default", "editor", "emacsclient", "mapi", and "xdg-email". Plugins may also add supported clients.

If mail is being sent, a to address is required. This can be supplied either on the commandline, by setting the submit_to configuration option in the branch itself or the child_submit_to configuration option in the submit branch.

Two formats are currently supported: "4" uses revision bundle format 4 and merge directive format 2. It is significantly faster and smaller than older formats. It is compatible with Bazaar 0.19 and later. It is the default. "0.9" uses revision bundle format 0.9 and merge directive format 1. It is compatible with Bazaar 0.12 - 0.18.

The merge directives created by bzr send may be applied using bzr merge or bzr pull by specifying a file containing a merge directive as the location.

See also:

merge, pull

serve

Purpose:

Run the bzr server.

Usage:

bzr serve

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--directory=ARG
 

Serve contents of this directory.

--usage

Show usage message and options.

--allow-writes

By default the server is a readonly server. Supplying --allow-writes enables write access to the contents of the served directory and below.

--port=ARG

Listen for connections on nominated port of the form [hostname:]portnumber. Passing 0 as the port number will result in a dynamically allocated port. The default port depends on the protocol.

--inet

Serve on stdin/out for use from inetd or sshd.

-h, --help

Show help message.

protocol:
--protocol=ARG

Protocol to serve.

--bzr

The Bazaar smart server protocol over TCP. (default port: 4155)

Aliases:

server

shelve

Purpose:

Temporarily set aside some changes from the current tree.

Usage:

bzr shelve [FILE...]

Options:
--all

Shelve all changes.

-v, --verbose

Display more information.

--list

List shelved changes.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--destroy

Destroy removed changes instead of shelving them.

-m ARG, --message=ARG
 

Message string.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

writer:
--plain

Plaintext diff output.

Description:

Shelve allows you to temporarily put changes you've made "on the shelf", ie. out of the way, until a later time when you can bring them back from the shelf with the 'unshelve' command. The changes are stored alongside your working tree, and so they aren't propagated along with your branch nor will they survive its deletion.

If shelve --list is specified, previously-shelved changes are listed.

Shelve is intended to help separate several sets of changes that have been inappropriately mingled. If you just want to get rid of all changes and you don't need to restore them later, use revert. If you want to shelve all text changes at once, use shelve --all.

If filenames are specified, only the changes to those files will be shelved. Other files will be left untouched.

If a revision is specified, changes since that revision will be shelved.

You can put multiple items on the shelf, and by default, 'unshelve' will restore the most recently shelved changes.

See also:

unshelve

sign-my-commits

Purpose:

Sign all commits by a given committer.

Usage:

bzr sign-my-commits [LOCATION] [COMMITTER]

Options:
--usage

Show usage message and options.

--dry-run

Don't actually sign anything, just print the revisions that would be signed.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

If location is not specified the local tree is used. If committer is not specified the default committer is used.

This does not sign commits that already have signatures.

split

Purpose:

Split a subdirectory of a tree into a separate tree.

Usage:

bzr split TREE

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This command will produce a target tree in a format that supports rich roots, like 'rich-root' or 'rich-root-pack'. These formats cannot be converted into earlier formats like 'dirstate-tags'.

The TREE argument should be a subdirectory of a working tree. That subdirectory will be converted into an independent tree, with its own branch. Commits in the top-level tree will not apply to the new subtree.

See also:

join

status

Purpose:

Display status summary.

Usage:

bzr status [FILE...]

Options:
-S, --short

Use short status indicators.

-v, --verbose

Display more information.

-V, --versioned
 

Only show versioned files.

--no-pending

Don't show pending merges.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--show-ids

Show internal object ids.

-c ARG, --change=ARG
 

Select changes introduced by the specified revision. See also "help revisionspec".

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

This reports on versioned and unknown files, reporting them grouped by state. Possible states are:

added

Versioned in the working copy but not in the previous revision.

removed

Versioned in the previous revision but removed or deleted in the working copy.

renamed

Path of this file changed from the previous revision; the text may also have changed. This includes files whose parent directory was renamed.

modified

Text has changed since the previous revision.

kind changed

File kind has been changed (e.g. from file to directory).

unknown

Not versioned and not matching an ignore pattern.

To see ignored files use 'bzr ignored'. For details on the changes to file texts, use 'bzr diff'.

Note that --short or -S gives status flags for each item, similar to Subversion's status command. To get output similar to svn -q, use bzr status -SV.

If no arguments are specified, the status of the entire working directory is shown. Otherwise, only the status of the specified files or directories is reported. If a directory is given, status is reported for everything inside that directory.

Before merges are committed, the pending merge tip revisions are shown. To see all pending merge revisions, use the -v option. To skip the display of pending merge information altogether, use the no-pending option or specify a file/directory.

If a revision argument is given, the status is calculated against that revision, or between two revisions if two are provided.

Aliases:

st, stat

See also:

diff, revert, status-flags

switch

Purpose:

Set the branch of a checkout and update.

Usage:

bzr switch TO_LOCATION

Options:
--usage

Show usage message and options.

--force

Switch even if local commits will be lost.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

For lightweight checkouts, this changes the branch being referenced. For heavyweight checkouts, this checks that there are no local commits versus the current bound branch, then it makes the local branch a mirror of the new location and binds to it.

In both cases, the working tree is updated and uncommitted changes are merged. The user can commit or revert these as they desire.

Pending merges need to be committed or reverted before using switch.

The path to the branch to switch to can be specified relative to the parent directory of the current branch. For example, if you are currently in a checkout of /path/to/branch, specifying 'newbranch' will find a branch at /path/to/newbranch.

Bound branches use the nickname of its master branch unless it is set locally, in which case switching will update the the local nickname to be that of the master.

tag

Purpose:

Create, remove or modify a tag naming a revision.

Usage:

bzr tag TAG_NAME

Options:
--force

Replace existing tags.

-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch in which to place the tag.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--delete

Delete this tag rather than placing it.

Description:

Tags give human-meaningful names to revisions. Commands that take a -r (--revision) option can be given -rtag:X, where X is any previously created tag.

Tags are stored in the branch. Tags are copied from one branch to another along when you branch, push, pull or merge.

It is an error to give a tag name that already exists unless you pass --force, in which case the tag is moved to point to the new revision.

To rename a tag (change the name but keep it on the same revsion), run bzr tag new-name -r tag:old-name and then bzr tag --delete oldname.

See also:

commit, tags

tags

Purpose:

List tags.

Usage:

bzr tags

Options:
--sort=ARG

Sort tags by different criteria. "alpha": Sort tags lexicographically (default). "time": Sort tags chronologically.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch whose tags should be displayed.

--usage

Show usage message and options.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-h, --help

Show help message.

Description:

This command shows a table of tag names and the revisions they reference.

See also:

tag

testament

Purpose:

Show testament (signing-form) of a revision.

Usage:

bzr testament [BRANCH]

Options:
-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--long

Produce long-format testament.

--strict

Produce a strict-format testament.

--usage

Show usage message and options.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

unbind

Purpose:

Convert the current checkout into a regular branch.

Usage:

bzr unbind

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

After unbinding, the local branch is considered independent and subsequent commits will be local only.

See also:

bind, checkouts

uncommit

Purpose:

Remove the last committed revision.

Usage:

bzr uncommit [LOCATION]

Options:
--dry-run

Don't actually make changes.

-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--usage

Show usage message and options.

--force

Say yes to all questions.

--local

Only remove the commits from the local branch when in a checkout.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

--verbose will print out what is being removed. --dry-run will go through all the motions, but not actually remove anything.

If --revision is specified, uncommit revisions to leave the branch at the specified revision. For example, "bzr uncommit -r 15" will leave the branch at revision 15.

Uncommit leaves the working tree ready for a new commit. The only change it may make is to restore any pending merges that were present before the commit.

See also:

commit

unshelve

Purpose:

Restore shelved changes.

Usage:

bzr unshelve [SHELF_ID]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

action:
--apply

Apply changes and remove from the shelf.

--delete-only

Delete changes without applying them.

--dry-run

Show changes, but do not apply or remove them.

Description:

By default, the most recently shelved changes are restored. However if you specify a shelf by id those changes will be restored instead. This works best when the changes don't depend on each other.

See also:

shelve

update

Purpose:

Update a tree to have the latest code committed to its branch.

Usage:

bzr update [DIR]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

This will perform a merge into the working tree, and may generate conflicts. If you have any local changes, you will still need to commit them after the update for the update to be complete.

If you want to discard your local changes, you can just do a 'bzr revert' instead of 'bzr commit' after the update.

Aliases:

up

See also:

pull, status-flags, working-trees

upgrade

Purpose:

Upgrade branch storage to current format.

Usage:

bzr upgrade [URL]

Options:
--usage

Show usage message and options.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Branch format:
--format=ARG

Upgrade to a specific format. See "bzr help formats" for details.

--1.14

A working-tree format that supports content filtering.

--1.14-rich-root
 

A variant of 1.14 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.6

A format that allows a branch to indicate that there is another (stacked) repository that should be used to access data that is not present locally.

--1.6.1-rich-root
 

A variant of 1.6 that supports rich-root data (needed for bzr-svn and bzr-git).

--1.9

A repository format using B+tree indexes. These indexes are smaller in size, have smarter caching and provide faster performance for most operations.

--1.9-rich-root
 

A variant of 1.9 that supports rich-root data (needed for bzr-svn and bzr-git).

--2a

First format for bzr 2.0 series. Uses group-compress storage. Provides rich roots which are a one-way transition.

--default

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--default-rich-root
 

Default format, rich root variant. (needed for bzr-svn and bzr-git).

--development-rich-root
 

Current development format. Supports rich roots. Can convert data to and from rich-root-pack (and anything compatible with rich-root-pack) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc.bazaar- vcs.org/latest/developers/development-repo.html before use.

--development-subtree
 

Current development format, subtree variant. Can convert data to and from pack-0.92-subtree (and anything compatible with pack-0.92-subtree) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc .bazaar-vcs.org/latest/developers/development- repo.html before use.

--dirstate

New in 0.15: Fast local operations. Compatible with bzr 0.8 and above when accessed over the network.

--dirstate-tags
 

New in 0.15: Fast local operations and improved scaling for network operations. Additionally adds support for tags. Incompatible with bzr < 0.15.

--knit

Format using knits. Recommended for interoperation with bzr <= 0.14.

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

New in 0.92: Pack-based format with data compatible with dirstate-tags format repositories. Interoperates with bzr repositories before 0.92 but cannot be read by bzr < 0.92. Previously called knitpack- experimental. For more information, see http://doc .bazaar-vcs.org/latest/developers/packrepo.html.

--rich-root

New in 1.0. Better handling of tree roots. Incompatible with bzr < 1.0.

--rich-root-pack
 

New in 1.0: A variant of pack-0.92 that supports rich- root data (needed for bzr-svn and bzr-git).

--weave

Pre-0.8 format. Slower than knit and does not support checkouts or shared repositories.

Description:

The check command or bzr developers may sometimes advise you to run this command. When the default format has changed you may also be warned during other operations to upgrade.

See also:

check

version

Purpose:

Show version of bzr.

Usage:

bzr version

Options:
--usage

Show usage message and options.

--short

Print just the version number.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

version-info

Purpose:

Show version information about this tree.

Usage:

bzr version-info [LOCATION]

Options:
--all

Include all possible information.

-v, --verbose

Display more information.

--include-history
 

Include the revision-history.

--check-clean

Check if tree is clean.

-q, --quiet

Only display errors and warnings.

--include-file-revisions
 

Include the last revision for each file.

--template=ARG

Template for the output.

--usage

Show usage message and options.

-h, --help

Show help message.

format:
--format=ARG

Select the output format.

--custom

Version info in Custom template-based format.

--python

Version info in Python format.

--rio

Version info in RIO (simple text) format (default).

Description:

You can use this command to add information about version into source code of an application. The output can be in one of the supported formats or in a custom format based on a template.

For example:

bzr version-info --custom \
  --template="#define VERSION_INFO \"Project 1.2.3 (r{revno})\"\n"

will produce a C header file with formatted string containing the current revision number. Other supported variables in templates are:

  • {date} - date of the last revision

  • {build_date} - current date

  • {revno} - revision number

  • {revision_id} - revision id

  • {branch_nick} - branch nickname

  • {clean} - 0 if the source tree contains uncommitted changes,

    otherwise 1

view

Purpose:

Manage filtered views.

Usage:

bzr view [FILE...]

Options:
--all

Apply list or delete action to all views.

-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--name=ARG

Name of the view to define, list or delete.

--switch=ARG

Name of the view to switch to.

--usage

Show usage message and options.

--delete

Delete the view.

Description:

Views provide a mask over the tree so that users can focus on a subset of a tree when doing their work. After creating a view, commands that support a list of files - status, diff, commit, etc - effectively have that list of files implicitly given each time. An explicit list of files can still be given but those files must be within the current view.

In most cases, a view has a short life-span: it is created to make a selected change and is deleted once that change is committed. At other times, you may wish to create one or more named views and switch between them.

To disable the current view without deleting it, you can switch to the pseudo view called off. This can be useful when you need to see the whole tree for an operation or two (e.g. merge) but want to switch back to your view after that.

Examples:

To define the current view:

bzr view file1 dir1 ...

To list the current view:

bzr view

To delete the current view:

bzr view --delete

To disable the current view without deleting it:

bzr view --switch off

To define a named view and switch to it:

bzr view --name view-name file1 dir1 ...

To list a named view:

bzr view --name view-name

To delete a named view:

bzr view --name view-name --delete

To switch to a named view:

bzr view --switch view-name

To list all views defined:

bzr view --all

To delete all views:

bzr view --delete --all

whoami

Purpose:

Show or set bzr user id.

Usage:

bzr whoami [NAME]

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--branch

Set identity for the current branch instead of globally.

--usage

Show usage message and options.

--email

Display email address only.

-h, --help

Show help message.

Examples:

Show the email of the current user:

bzr whoami --email

Set the current user:

bzr whoami "Frank Chu <fchu@example.com>"