Bazaar User Reference

Version: 1.1.0
Generated:2008-10-17

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    Make a directory into a versioned branch.
branch  Create a new copy of a 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 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 wont 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

Criss-Cross

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

If you encounter criss-crosses, you can use merge --weave instead, which should provide a much better result.

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.

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.

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.

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 and SFTP needs a (user, password) to authenticate against a host (SFTP can use ssh keys too, but we don't talk about that here as ssh agents provide a better solution).

  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
password=precious

HTTPS, SFTP servers and their proxy

At company.com, the server hosting released and integration code is behind a proxy, the two servers 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
password=pass2

# 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.) Support for Launchpad's central bug tracker is built in. For other bug trackers, configuration is required in advance so that the correct URL can be recorded.

In addition to Launchpad, Bazaar directly supports the generation of URLs appropriate for Bugzilla and Trac. If your project uses a different bug tracker, it is easy to add support for 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.

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 header for bazaar.conf is [DEFAULT], which is case sensitive. The default section provides for setting variables which can be overridden with the branch config file.

For locations.conf, the variables from the section with the longest matching section header are used to the exclusion of other potentially valid section headers. A section header uses the path for the branch as the section header. Some examples include:

[http://mybranches.isp.com/~jdoe/branchdir]
[/home/jdoe/branches/]
Section variables

A section variable resides within a section. A section variable contains a variable name, an equals sign and a value. For example:

email            = John Doe <jdoe@isp.com>
check_signatures = require
Variable policies

Variables defined in a section affect the named directory or URL plus any locations they contain. Policies can be used to change how a variable value is interpreted for contained locations. Currently there are three policies available:

none:
the value is interpreted the same for contained locations. This is the default behaviour.
norecurse:
the value is only used for the exact location specified by the section name.
appendpath:
for contained locations, any additional path components are appended to the value.

Policies are specified by keys with names of the form "$var:policy". For example, to define the push location for a tree of branches, the following could be used:

[/top/location]
push_location = sftp://example.com/location
push_location:policy = appendpath

With this configuration, the push location for /top/location/branch1 would be sftp://example.com/location/branch1.

The main configuration file, bazaar.conf

bazaar.conf only allows one section called [DEFAULT]. This default section contains the default configuration options for all branches. The default section can be overriden by providing a branch-specific section in locations.conf.

A typical bazaar.conf section often looks like the following:

[DEFAULT]
email             = John Doe <jdoe@isp.com>
editor            = /usr/bin/vim
check_signatures  = check-available
create_signatures = when-required

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

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.

check_signatures

Defines the behavior for signatures.

require
The gnupg signature for revisions must be present and must be valid.
ignore
Do not check gnupg signatures of revisions.
check-available
(default) If gnupg signatures for revisions are present, check them. Bazaar will fail if it finds a bad signature, but will not fail if no signature is present.

create_signatures

Defines the behaviour of signing revisions.

always
Sign every new revision that is committed.
when-required
(default) Sign newly committed revisions only when the branch requires signed revisions.
never
Refuse to sign newly committed revisions, even if the branch requires signatures.

recurse

Only useful in locations.conf. Defines whether or not the configuration for this section applies to subdirectories:

true
(default) This section applies to subdirectories as well.
false
This section only applies to the branch at this directory and not branches below it.

gpg_signing_command

(Default: "gpg"). Which program should be used to sign and check revisions. For example:

gpg_signing_command = /usr/bin/gnpg

bzr_remote_path

(Default: "bzr"). The path to the command that should be used to run the smart server for bzr. This value may only be specified in locations.conf, because:

  • it's needed before branch.conf is accessible
  • allowing remote branch.conf files to specify commands would be a security risk

It is overridden by the BZR_REMOTE_PATH environment variable.

smtp_server

(Default: "localhost"). SMTP server to use when Bazaar needs to send email, eg. with merge-directive --mail-to, or the bzr-email plugin.

smtp_username, smtp_password

User and password to authenticate to the SMTP server. If smtp_username is set, and smtp_password is not, Bazaar will prompt for a password. These settings are only needed if the SMTP server requires authentication to send mail.

mail_client

A mail client to use for sending merge requests. By default, bzr will try to use mapi on Windows. On other platforms, it will try xdg-email. If either of these fails, it will fall back to editor.

Supported values for specific clients:

evolution:Use Evolution.
kmail:Use KMail.
mutt:Use Mutt.
thunderbird:Use Mozilla Thunderbird or Icedove. For Thunderbird/Icedove 1.5, this works around some bugs that xdg-email doesn't handle.

Supported generic values are:

default:See above.
editor:Use your editor to compose the merge request. This also uses your commit id, (see bzr whoami), smtp_server and (optionally) smtp_username and smtp_password.
mapi:Use your preferred e-mail client on Windows.
xdg-email:Use xdg-email to run your preferred mail program

submit_branch

The branch you intend to submit your current work to. This is automatically set by bzr send, and is also used by the submit: revision spec. This should usually be set on a per-branch or per-location basis.

public_branch

A publically-accessible version of this branch (implying that this version is not publically-accessible). Used (and set) by bzr send.

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

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.

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

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

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

Storage Formats

These formats can be used for creating branches, working trees, and repositories.

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.
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.
knit:(native) Format using knits. Recommended for interoperation with bzr <= 0.14.
rich-root:(native) New in 1.0. Better handling of tree roots. Incompatible with bzr < 1.0

Experimental formats are shown below.

rich-root-pack:(native) New in 1.0: Pack-based format with data compatible with rich-root format repositories. Incompatible with bzr < 1.0

Deprecated formats are shown below.

metaweave:(native) Transitional format in 0.8. Slower than knit.
weave:(native) Pre-0.8 format. Slower than knit and does not support checkouts or shared repositories.

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.

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

-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.
-Dhashcache Log every time a working file is read to determine its hash.
-Dhooks Trace hook execution.
-Dhttp Trace http connections, requests and responses
-Dhpss Trace smart protocol requests and responses.
-Dindex Trace major index operations.
-Dlock Trace when lockdir locks are taken or released.
-Dmerge Emit information for debugging merges.

Hooks

post_push

Run after push has completed.

The hook signature is (push_result), containing the members

source_branch
Where the data is being pushed from (read locked). This should be the lowest latency branch.
target_branch
The direct location where data is being sent (write locked).
master_branch
Either target_branch, or if the target is a bound branch, it will be the master location (write locked).
local_branch
If the target is a bound branch, this will be the target branch, else it will be None.
old_revno
The revision number (eg 10) of the branch before the push.
old_revid
The revision id (eg joe@foo.com-1234234-aoeua34) before the push.
new_revno
The revision number (eg 12) of the branch after the push.
new_revid
The revision id (eg joe@foo.com-5676566-boa234a) after the push.

post_pull

Run after pull has completed.

The hook signature is (push_result) containing the members (source, local, master, old_revno, old_revid, new_revno, new_revid) where local is the local target branch or None, master is the target master branch, and the rest should be self explanatory. The source is read-locked and the target branches are write-locked. Source will be the local low-latency branch.

pre_commit

Run prefore commit has completed.

The hook signature is (local, master, old_revno, old_revid, future_revno, future_revid, tree_delta, future_tree) where old_revno is NULL_REVISION for the first commit to a branch, tree_delta is a TreeDelta object describing changes from the basis revision, and future_tree is an in-memory tree obtained from CommitBuilder.revision_tree(). Hooks MUST NOT modify tree_delta and future_tree.

post_commit

Run after commit has completed.

The hook signature is (local, master, old_revno, old_revid, new_revno, new_revid) old_revid is NULL_REVISION for the first commit to a branch.

post_uncommit

Run after uncommit has completed.

The api signature is (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.

set_rh

Run after the branch's revision history has been modified (push, pull, commit and uncommit can all modify the revision history).

The hook signature is (branch, revision_history), and the branch will be write-locked.

See also Using hooks in the User Guide.

Revision Identifiers

A revision, or a range bound, can be one of the following.

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

Further details are given below.

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
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.
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'
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.
before:

Supply any revision spec to return the parent of that revision. It is an error to request the parent of the null revision (before:0). This is mostly useful when inspecting revisions that are not in the revision history of a branch.

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:revid:aaaa..revid:aaaa
      -> Find the changes between revision 'aaaa' and its parent.
         (what changes did 'aaaa' introduce)
tag:

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

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

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.
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
branch:

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

Examples:

branch:/path/to/branch
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 comands. 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:

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

--no-recurse

Don't recursively add the contents of directories.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--file-ids-from=ARG
 

Lookup file ids from this tree.

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

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.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--long

Show commit date in annotations.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

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

See also:

checkouts, unbind

branch

Purpose:

Create a new copy of a branch.

Usage:

bzr branch FROM_LOCATION [TO_LOCATION]

Options:
-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

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:
-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:
-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--name-from-revision
 

The path name in the old tree.

-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 consistency of branch history.

Usage:

bzr check [BRANCH]

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

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

Output fields:

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.

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.

-h, --help

Show help message.

--files-from=ARG
 

Get file contents from this tree.

-q, --quiet

Only display errors and warnings.

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

-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

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.

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

-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:

If no arguments are given, the entire tree is committed.

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.

If 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>".

A selected-file 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.)

Note: A selected-file commit after a merge is not yet supported.

Aliases:

ci, checkin

See also:

bugs, uncommit

conflicts

Purpose:

List files with conflicts.

Usage:

bzr conflicts

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

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

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/
Exit values:

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

Aliases:

di, dif

See also:

status

export

Purpose:

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

Usage:

bzr export DEST [BRANCH]

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.

--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:
-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:
--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:

To remove patterns from the ignore list, edit the .bzrignore file.

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 './'.

Ignore patterns specifying absolute paths are not allowed.

Ignore 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

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

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"
See also:

ignored, status

ignored

Purpose:

List ignored files and the patterns that matched them.

Usage:

bzr ignored

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

See also:

ignore

info

Purpose:

Show information about a working tree, branch or repository.

Usage:

bzr info [LOCATION]

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. Statistical information is included with each report.

Branches and working trees will also report any missing revisions.

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.

--append-revisions-only
 

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

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Branch Format:
--format=ARG

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

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

--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: Pack-based format with data compatible with rich-root format repositories. Incompatible with bzr < 1.0

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

-h, --help

Show help message.

Repository format:
--format=ARG

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

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

--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: Pack-based format with data compatible with rich-root format repositories. Incompatible with bzr < 1.0

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

log

Purpose:

Show log of a branch, file, or directory.

Usage:

bzr log [LOCATION]

Options:
-v, --verbose

Show files changed in each revision.

-q, --quiet

Only display errors and warnings.

-l N, --limit=N
 

Limit the output to the first N revisions.

--forward

Show from oldest to newest.

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

-h, --help

Show help message.

Log format:
--log-format=ARG
 

Use specified log format.

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

By default show the log of the branch containing the working directory.

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

Examples:

Log the current branch:

bzr log

Log a file:

bzr log foo.c

Log the last 10 revisions of a branch:

bzr log -r -10.. http://server/branch

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.

--versioned

Print versioned files.

--unknown

Print unknown files.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--non-recursive
 

Don't recurse into subdirectories.

--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 [BRANCH]

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.

--uncommitted

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

-d ARG, --directory=ARG
 

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

--show-base

Show base revision text in conflicts.

-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 branch is the branch you will merge from. By default, it will merge the latest revision. If you specify a revision, that revision will be merged. If you specify two revisions, the first will be used as a BASE, and the second one as OTHER. Revision numbers are always relative to the specified branch.

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
See also:

remerge, 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.

--mine-only

Display changes in the local branch only.

--show-ids

Show internal object ids.

--theirs-only

Display changes in the remote branch only.

-v, --verbose

Display more information.

Log format:
--log-format=ARG
 

Use specified log format.

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

See also:

merge, pull

mkdir

Purpose:

Create a new versioned directory.

Usage:

bzr mkdir DIR...

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:
--after

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

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

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

See also:

info

pack

Purpose:

Compress the data within a repository.

Usage:

bzr pack [BRANCH_OR_REPO]

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:
-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 the path where each one is located and a short description of each.

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:
-v, --verbose

Show logs of pulled revisions.

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

--overwrite

Ignore differences between branches and overwrite unconditionally.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

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.

See also:

push, status-flags, update

push

Purpose:

Update a mirror of this branch.

Usage:

bzr push [LOCATION]

Options:
--remember

Remember the specified location as a default.

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

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

-d ARG, --directory=ARG
 

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

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

-h, --help

Show help message.

Target type:
--branch

Reconfigure to a branch.

--checkout

Reconfigure to a checkout.

--lightweight-checkout
 

Reconfigure to a lightweight checkout.

--tree

Reconfigure to a tree.

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.

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.

--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:
--new

Remove newly-added files.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-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 and delete them if they can easily be recovered using revert.

You can specify one or more files, and/or --new. If you specify --new, only 'added' files will be removed. If you specify both, then new files in the specified directories will be removed. If the directories are also new, they will also be removed.

Aliases:

rm

remove-tree

Purpose:

Remove the working tree from a given branch/checkout.

Usage:

bzr remove-tree [LOCATION]

Options:
-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:
-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:
--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.

--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:
-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:
-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 submiting changes.

Usage:

bzr send [SUBMIT_BRANCH] [PUBLIC_BRANCH]

Options:
-f ARG, --from=ARG
 

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

--remember

Remember submit and public branch.

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

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-o ARG, --output=ARG
 

Write directive to this file.

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

-v, --verbose

Display more information.

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 "evolution", "kmail", "mutt", and "thunderbird"; generic options are "default", "editor", "mapi", and "xdg-email".

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

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.

See also:

merge

serve

Purpose:

Run the bzr server.

Usage:

bzr serve

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.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--directory=ARG
 

Serve contents of this directory.

--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 is 4155.

--inet

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

-h, --help

Show help message.

Aliases:

server

sign-my-commits

Purpose:

Sign all commits by a given committer.

Usage:

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

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

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.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

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

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

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.

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

See also:

commit, tags

tags

Purpose:

List tags.

Usage:

bzr tags

Options:
--sort=ARG

Sort tags by different criteria.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch whose tags should be displayed.

--show-ids

Show internal object ids.

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

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

unbind

Purpose:

Convert the current checkout into a regular branch.

Usage:

bzr unbind

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.

--force

Say yes to all questions.

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

In the future, uncommit will create a revision bundle, which can then be re-applied.

See also:

commit

update

Purpose:

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

Usage:

bzr update [DIR]

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

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

--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: Pack-based format with data compatible with rich-root format repositories. Incompatible with bzr < 1.0

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

--check-clean

Check if tree is clean.

--include-history
 

Include the revision-history.

-q, --quiet

Only display errors and warnings.

--template=ARG

Template for the output.

--include-file-revisions
 

Include the last revision for each file.

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

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

whoami

Purpose:

Show or set bzr user id.

Usage:

bzr whoami [NAME]

Options:
--email

Display email address only.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--branch

Set identity for the current branch instead of globally.

-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>"