Bazaar User Reference

Version: 1.12
Generated:2009-02-13

Contents


About This Manual

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

Introduction including a list of commonly used commands:

bzr help

List of topics and a summary of each:

bzr help topics

List of commands and a summary of each:

bzr help commands

More information about a particular topic or command:

bzr help topic-or-command-name

The following web sites provide further information on Bazaar:

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

Concepts

Branches

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

Related commands:

init    Change a directory into a versioned branch.
branch  Create a new 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 of the branch needs to be updated). Heavyweight checkouts will generally be faster for any command that uses the history but does not change it, but if the master branch is on the same disk then there won't be a noticeable difference.

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

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

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

Related commands:

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

Criss-Cross

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

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

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

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

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

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

Storage Formats

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

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

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

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

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

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

Patterns

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

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

Patterns may include globbing wildcards such as:

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

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

Repositories

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

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

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

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

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

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

Related commands:

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

Rules

Introduction

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

[name *.bat]
eol = dos

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

Preferences like these are useful for commands and plugins wishing to provide custom behaviour for selected files in selected branches.

Files

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

Rule Patterns

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

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

Standalone Trees

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

Related Commands:

init    Make a directory into a versioned branch.

Branches out of sync

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

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

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

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

Working Trees

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

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

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

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

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

Useful commands:

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

Lists

Authentication Settings

Intent

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

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

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

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

Instead of using:

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

you simply use:

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

provided you have created the following authentication.conf file:

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

Authentication definitions

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

  1. user and password

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

  1. user, realm and password

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

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

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

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

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

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

File format

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

Each section describes an authentication definition.

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

Each section should define:

  • user: the login to be used,

Each section could define:

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

Examples

Personal projects hosted outside

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

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

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

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

Source hosting provider

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

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

HTTPS, SFTP servers and their proxy

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

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

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

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

Planned enhancements

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

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

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

Bug Tracker Settings

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

Launchpad

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

bugzilla_<tracker_abbreviation>_url

If present, the location of the Bugzilla bug tracker referred to by <tracker_abbreviation>. This option can then be used together with bzr commit --fixes to mark bugs in that tracker as being fixed by that commit. For example:

bugzilla_squid_url = http://www.squid-cache.org/bugs

would allow bzr commit --fixes squid:1234 to mark Squid's bug 1234 as fixed.

trac_<tracker_abbrevation>_url

If present, the location of the Trac instance referred to by <tracker_abbreviation>. This option can then be used together with bzr commit --fixes to mark bugs in that tracker as being fixed by that commit. For example:

trac_twisted_url = http://www.twistedmatrix.com/trac

would allow bzr commit --fixes twisted:1234 to mark Twisted's bug 1234 as fixed.

bugtracker_<tracker_abbrevation>_url

If present, the location of a generic bug tracker instance referred to by <tracker_abbreviation>. The location must contain an {id} placeholder, which will be replaced by a specific bug ID. This option can then be used together with bzr commit --fixes to mark bugs in that tracker as being fixed by that commit. For example:

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

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

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

for CPAN's RT bug tracker.

Configuration Settings

Environment settings

While most configuration is handled by configuration files, some options which may be semi-permanent can also be controlled through the environment.

BZR_EMAIL

Override the email id used by Bazaar. Typical format:

"John Doe <jdoe@example.com>"

See also the email configuration value.

BZR_PROGRESS_BAR

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

BZR_SIGQUIT_PDB

Control whether SIGQUIT behaves normally or invokes a breakin debugger.

  • 0 = Standard SIGQUIT behavior (normally, exit with a core dump)
  • 1 = Invoke breakin debugger (default)

BZR_HOME

Override the home directory used by Bazaar.

BZR_SSH

Select a different SSH implementation.

BZR_PDB

Control whether to launch a debugger on error.

  • 0 = Standard behavior
  • 1 = Launch debugger

BZR_REMOTE_PATH

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

See also the bzr_remote_path configuration value.

BZR_EDITOR

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

BZR_PLUGIN_PATH

The path to the plugins directory that Bazaar should use.

BZRPATH

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

Configuration files

Location

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

There are three primary configuration files in this location:

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

Each branch can also contain a configuration file that sets values specific to that branch. This file is found at .bzr/branch/branch.conf within the branch. This file is visible to all users of a branch, if you wish to override one of the values for a branch with a setting that is specific to you then you can do so in locations.conf.

General format

An ini file has three types of contructs: section headers, section variables and comments.

Comments

A comment is any line that starts with a "#" (sometimes called a "hash mark", "pound sign" or "number sign"). Comment lines are ignored by Bazaar when parsing ini files.

Section headers

A section header is a word enclosed in brackets that starts at the begining of a line. A typical section header looks like this:

[DEFAULT]

The only valid section headers for bazaar.conf currently are [DEFAULT] and [ALIASES]. Section headers are case sensitive. The default section provides for setting variables which can be overridden with the branch config file.

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

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

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

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

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

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

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

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

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

The main configuration file, bazaar.conf

bazaar.conf allows two sections: [DEFAULT] and [ALIASES]. The default section contains the default configuration options for all branches. The default section can be overriden by providing a branch-specific section in locations.conf.

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

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

The branch location configuration file, locations.conf

locations.conf allows one to specify overriding settings for a specific branch. The format is almost identical to the default section in bazaar.conf with one significant change: The section header, instead of saying default, will be the path to a branch that you wish to override a value for. The '?' and '*' wildcards are supported:

[/home/jdoe/branches/nethack]
email = Nethack Admin <nethack@nethack.com>

[http://hypothetical.site.com/branches/devel-branch]
create_signatures = always
check_signatures  = always

[http://bazaar-vcs.org/bzr/*]
check_signatures  = require

The authentication configuration file, authentication.conf

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

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

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

Common variable options

email

The email address to use when committing a branch. Typically takes the form of:

email = Full Name <account@hostname.tld>

editor

The path of the editor that you wish to use if bzr commit is run without a commit message. This setting is trumped by the environment variable BZR_EDITOR, and overrides the VISUAL and EDITOR environment variables.

log_format

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

check_signatures

Defines the behavior for signatures.

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

create_signatures

Defines the behaviour of signing revisions.

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

recurse

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

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

gpg_signing_command

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

gpg_signing_command = /usr/bin/gnpg

bzr_remote_path

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

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

It is overridden by the BZR_REMOTE_PATH environment variable.

smtp_server

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

smtp_username, smtp_password

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

mail_client

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

Supported values for specific clients:

claws:Use Claws. This skips a dialog for attaching files.
evolution:Use Evolution.
kmail:Use KMail.
mutt:Use Mutt.
thunderbird:Use Mozilla Thunderbird or Icedove. For Thunderbird/Icedove 1.5, this works around some bugs that xdg-email doesn't handle.

Supported generic values are:

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

submit_branch

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

public_branch

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

Branch type specific options

These options apply only to branches that use the dirstate-tags or later format. They are usually set in .bzr/branch/branch.conf automatically, but may be manually set in locations.conf or bazaar.conf.

append_revisions_only

If set to "True" then revisions can only be appended to the log, not removed. A branch with this setting enabled can only pull from another branch if the other branch's log is a longer version of its own. This is normally set by bzr init --append-revisions-only.

parent_location

If present, the location of the default branch for pull or merge. This option is normally set by pull --remember or merge --remember.

push_location

If present, the location of the default branch for push. This option is normally set by push --remember.

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

Current Storage Formats

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

See bzr help formats for more about storage formats.

Environment Variables

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

Files

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

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

A typical config file might look something like:

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

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

Global Options

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

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

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

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

Hooks

Introduction

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

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

See Using hooks in the User Guide for examples.

The class that contains each hook is given in parentheses immediately after each hook type below.

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

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

  • The remote branch is on the same machine as the client, and the client has plugins enabled.
  • The connection is via a smart server (accessed with a URL starting with "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://" URL when a smart server is available via HTTP), and that server has plugins enabled.

open (Branch)

Called after a Branch object is opened, with the Branch object. Runs on the client and on the server.

post_push (Branch)

Run after push has completed. Runs on the client.

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 (Branch)

Run after pull has completed. Runs on the client.

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.

start_commit (MutableTree)

Run on the working tree before commit starts processing it. Runs on the client.

Unlike the pre_commit hook (see below), the start_commit hook can safely change the working tree.

The hook signature is (tree) where tree is a MutableTree object.

pre_commit (Branch)

Run before commit has completed. Runs on the client.

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 (Branch)

Run after commit has completed. Runs on the client.

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 (Branch)

Run after uncommit has completed. Runs on the client.

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.

pre_change_branch_tip (Branch)

Run before a branch tip has been changed, while the branch is write-locked. Runs on the client and on the server. Note that push, pull, commit and uncommit all invoke this hook.

The hook signature is (params), where params is an object containing the members

branch
The branch whose tip has been changed.
old_revno
The revision number (eg 10) of the branch before the change.
old_revid
The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
new_revno
The revision number (eg 12) of the branch after the change.
new_revid
The revision id (eg joe@foo.com-5676566-boa234a) after the change.

The old_revno and new_revno members are integers, as the head revision never has a dotted revision number.

post_change_branch_tip (Branch)

Run after a branch tip has been changed but while the branch is still write-locked. Runs on the client and on the server. Note that push, pull, commit and uncommit all invoke this hook.

The hook signature is (params), where params is an object containing the members

branch
The branch whose tip has been changed.
old_revno
The revision number (eg 10) of the branch before the change.
old_revid
The revision id (eg joe@foo.com-1234234-aoeua34) before the change.
new_revno
The revision number (eg 12) of the branch after the change.
new_revid
The revision id (eg joe@foo.com-5676566-boa234a) after the change.

The old_revno and new_revno members are integers, as the head revision never has a dotted revision number.

set_rh (Branch)

Note: This hook is now deprecated and will be removed in the near future. Please use the post_change_branch_tip hook instead.

transform_fallback_location (Branch)

Invoked as a stacked branch activates its fallback locations.

The hook signature is (branch, url) where:

branch
The branch being opened. Note that as it does not yet have its fallback locations activated, the branch should be treated as half-built.
url
The URL that the branch specified for its fallback location.

The hook must return a URL for the branch containing the fallback location. If multiple hooks are registered, the order in which they will be called is undefined and subject to change.

(New in 1.9)

server_started (SmartTCPServer)

Invoked whenever the server starts serving a directory. Runs on the server.

The hook signature is (backing urls, public url), where:

backing_url
A list of (string) URLs giving the server-specific directory locations.
public_url
The public URL for the directory.

server_stopped (SmartTCPServer)

Invoked whenever the server stops serving a directory. Runs on the server.

The hook signature is the same as server_started.

lock_acquired (LockDir)

Called with a LockResult object when a lock has been successfully acquired. Runs on the client and on the server.

(New in 1.8.)

lock_released (LockDir)

Called with a LockResult object when a lock has been successfully released. Runs on the client.

(New in 1.8.)

commit_message_template (msgeditor)

Invoked by commit to generate a commit message template. Each hook can modify the commit message template. The hook signature is (commit, start_message), where:

commit
A commit object, for the commit in progress
start_message
The original commit message, None initially.

The hook should return a new commit message template.

(New in 1.10.)

Log formats

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

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

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

[DEFAULT]
log_format = short

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

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

Other Storage Formats

Experimental formats are shown below.

development-wt5:
 (native) A working-tree format that supports views and content filtering.
development-wt5-rich-root:
 (native) A variant of development-wt5 that supports rich-root data (needed for bzr-svn).
development:(native) Current development format. Can convert data to and from pack-0.92 (and anything compatible with pack-0.92) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc.bazaar- vcs.org/latest/developers/development-repo.html before use.
development-subtree:
 (native) Current development format, subtree variant. Can convert data to and from pack-0.92-subtree (and anything compatible with pack-0.92-subtree) format repositories. Repositories and branches in this format can only be read by bzr.dev. Please read http://doc .bazaar-vcs.org/latest/developers/development-repo.html before use.

Deprecated formats are shown below.

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

See bzr help formats for more about storage formats.

Revision Identifiers

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

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

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

The keywords used as revision selection methods are the following:

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

In addition, plugins can provide other keywords.

A detailed description of each keyword is given below.

revid:

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

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

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

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

Examples:

$ bzr diff -r submit:
ancestor:

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

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

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

Examples:

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

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

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

bzr log -r date:yesterday..

Examples:

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

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

Examples:

branch:/path/to/branch
tag:

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

revno:

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

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

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

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

Examples:

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

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

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

Standard Options

Standard options are legal for all commands.

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

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

Status Flags

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

xxx   <filename>

where the columns' meanings are as follows.

Column 1 - versioning/renames:

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

Column 2 - contents:

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

Column 3 - execute:

* The execute bit was changed

URL Identifiers

Supported URL prefixes:

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

Commands

add

Purpose:

Add specified files or directories.

Usage:

bzr add [FILE...]

Options:
--dry-run

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

-v, --verbose

Display more information.

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

alias

Purpose:

Set/unset and display aliases.

Usage:

bzr alias [NAME]

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

--remove

Remove the alias.

-h, --help

Show help message.

Examples:

Show the current aliases:

bzr alias

Show the alias specified for 'll':

bzr alias ll

Set an alias for 'll':

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

To remove an alias for 'll':

bzr alias --remove ll

annotate

Purpose:

Show the origin of each line in a file.

Usage:

bzr annotate FILENAME

Options:
--all

Show annotations on all lines.

-v, --verbose

Display more information.

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

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

See also:

checkouts, unbind

branch

Purpose:

Create a new copy of a branch.

Usage:

bzr branch FROM_LOCATION [TO_LOCATION]

Options:
--stacked

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

-v, --verbose

Display more information.

--standalone

Do not use a shared repository, even if available.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--hardlink

Hard-link working tree files where possible.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

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

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

Aliases:

get, clone

See also:

checkout

break-lock

Purpose:

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

Usage:

bzr break-lock [LOCATION]

Options:
-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 working tree structure, branch consistency and repository history.

Usage:

bzr check [PATH]

Options:
-v, --verbose

Display more information.

--tree

Check the working tree related to the current directory.

-q, --quiet

Only display errors and warnings.

--repo

Check the repository related to the current directory.

--branch

Check the branch related to the current directory.

-h, --help

Show help message.

Description:

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

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

revisions: This is just the number of revisions checked. It doesn't

indicate a problem.

versionedfiles: This is just the number of versionedfiles checked. It

doesn't indicate a problem.

unreferenced ancestors: Texts that are ancestors of other texts, but

are not properly referenced by the revision ancestry. This is a subtle problem that Bazaar can work around.

unique file texts: This is the total number of unique file contents

seen in the checked revisions. It does not indicate a problem.

repeated file texts: This is the total number of repeated texts seen

in the checked revisions. Texts can be repeated when their file entries are modified, but the file contents are not. It does not indicate a problem.

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

Examples:

Check the tree and branch at 'foo':

bzr check --tree --branch foo

Check only the repository at 'bar':

bzr check --repo bar

Check everything at 'baz':

bzr check baz
See also:

reconcile

checkout

Purpose:

Create a new checkout of an existing branch.

Usage:

bzr checkout [BRANCH_LOCATION] [TO_LOCATION]

Options:
-v, --verbose

Display more information.

-h, --help

Show help message.

--files-from=ARG
 

Get file contents from this tree.

-q, --quiet

Only display errors and warnings.

--hardlink

Hard-link working tree files where possible.

--lightweight

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

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

-x ARG, --exclude=ARG
 

Do not consider changes made to a given path.

-m ARG, --message=ARG
 

Description of the new revision.

--local

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

-h, --help

Show help message.

Description:

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.

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

bzr commit foo -x foo/bar

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

Exit values:

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

Examples:

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

bzr diff

Difference between the working tree and revision 1:

bzr diff -r1

Difference between revision 2 and revision 1:

bzr diff -r1..2

Difference between revision 2 and revision 1 for branch xxx:

bzr diff -r1..2 xxx

Show just the differences for file NEWS:

bzr diff NEWS

Show the differences in working tree xxx for file NEWS:

bzr diff xxx/NEWS

Show the differences from branch xxx to this working tree:

bzr diff --old xxx

Show the differences between two branches for file NEWS:

bzr diff --old xxx --new yyy NEWS

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

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

di, dif

See also:

status

export

Purpose:

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

Usage:

bzr export DEST [BRANCH_OR_SUBDIR]

Options:
-v, --verbose

Display more information.

--format=ARG

Type of file to export to.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

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

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

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

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

Examples:

Ignore the top level Makefile:

bzr ignore ./Makefile

Ignore class files in all directories:

bzr ignore "*.class"

Ignore .o files under the lib directory:

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

Ignore .o files under the lib directory:

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

Ignore everything but the "debian" toplevel directory:

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

ignored, patterns, status

ignored

Purpose:

List ignored files and the patterns that matched them.

Usage:

bzr ignored

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

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

Alternatively, to list just the files:

bzr ls --ignored
See also:

ignore, ls

info

Purpose:

Show information about a working tree, branch or repository.

Usage:

bzr info [LOCATION]

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

--1.6

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

--1.6.1-rich-root
 

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

--1.9

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

--1.9-rich-root
 

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

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

--development

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

--development-subtree
 

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

--development-wt5
 

A working-tree format that supports views and content filtering.

--development-wt5-rich-root
 

A variant of development-wt5 that supports rich-root data (needed for bzr-svn).

--dirstate

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

--dirstate-tags
 

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

--knit

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

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

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

--rich-root

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

--rich-root-pack
 

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

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

--1.6

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

--1.6.1-rich-root
 

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

--1.9

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

--1.9-rich-root
 

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

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

--development

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

--development-subtree
 

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

--development-wt5
 

A working-tree format that supports views and content filtering.

--development-wt5-rich-root
 

A variant of development-wt5 that supports rich-root data (needed for bzr-svn).

--dirstate

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

--dirstate-tags
 

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

--knit

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

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

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

--rich-root

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

--rich-root-pack
 

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

--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 historical log for a branch or subset of a branch.

Usage:

bzr log [LOCATION]

Options:
-v, --verbose

Show files changed in each revision.

-q, --quiet

Only display errors and warnings.

-p, --show-diff
 

Show changes made in each revision as a patch.

-n N, --levels=N
 

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

-l N, --limit=N
 

Limit the output to the first N revisions.

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

-c ARG, --change=ARG
 

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

-h, --help

Show help message.

Log format:
--log-format=ARG
 

Use specified log format.

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

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

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

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

Output control:

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

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

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

Note that the default number of levels to display is a function of the log format. If the -n option is not used, short and line show just the top level (mainline) while long shows all levels of merged revisions.

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

Ordering control:
 

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

Revision filtering:
 

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

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

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

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

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

Path filtering:

If a parameter is given and it's not a branch, the log will be filtered to show only those revisions that changed the nominated file or directory.

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

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

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

In this case:

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

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

Note: If the path is a directory, only revisions that directly changed that directory object are currently shown. This is considered a bug. (Support for filtering against multiple files and for files within a directory is under development.)

Other filtering:
 

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

Tips & tricks:

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

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

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

[ALIASES]
tip = log -r-1 -n1
top = log -r-10.. --short --forward
show = log -v -p -n1 --long

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

As many GUI tools and Web interfaces do, you may prefer viewing history collapsed initially. If you are interested in looking deeper into a particular merge X, use bzr log -n0 -rX. If you like working this way, you may wish to either:

  • change your default log format to short (or line)
  • add this alias: log = log -n1

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

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

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

See also:

log-formats, revisionspec

ls

Purpose:

List files in a tree.

Usage:

bzr ls [PATH]

Options:
--from-root

Print paths relative to the root of the branch.

--ignored

Print ignored files.

--kind=ARG

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

-v, --verbose

Display more information.

-V, --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 [LOCATION]

Options:
--pull

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

--remember

Remember the specified location as a default.

--force

Merge even if the destination tree has uncommitted changes.

-v, --verbose

Display more information.

--reprocess

Reprocess to reduce spurious conflicts.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

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

--preview

Instead of merging, show a diff of the merge.

-c ARG, --change=ARG
 

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

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Merge algorithm:
--merge-type=ARG
 

Select a particular merge algorithm.

--diff3

Merge using external diff3

--lca

LCA-newness merge

--merge3

Native diff3-style merge

--weave

Weave-based merge

Description:

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

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

Revision numbers are always relative to the branch being merged.

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

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

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

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

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

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

Examples:

To merge the latest revision from bzr.dev:

bzr merge ../bzr.dev

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

bzr merge -r 82 ../bzr.dev

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

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

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

bzr merge /tmp/merge

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.

--include-merges
 

Show merged revisions.

--mine-only

Display changes in the local branch only.

--my-revision=ARG
 

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

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

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

--theirs-only

Display changes in the remote branch only.

-v, --verbose

Display more information.

Log format:
--log-format=ARG
 

Use specified log format.

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

OTHER_BRANCH may be local or remote.

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

Examples:

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

bzr missing

Determine the missing revisions between this and another branch:

bzr missing http://server/branch

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

bzr missing -r ..-10

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

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

merge, pull

mkdir

Purpose:

Create a new versioned directory.

Usage:

bzr mkdir DIR...

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

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

See also:

info

pack

Purpose:

Compress the data within a repository.

Usage:

bzr pack [BRANCH_OR_REPO]

Options:
-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 version of plugin and a short description of each.

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

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

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

pull

Purpose:

Turn this branch into a mirror of another branch.

Usage:

bzr pull [LOCATION]

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

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

See also:

push, status-flags, update

push

Purpose:

Update a mirror of this branch.

Usage:

bzr push [LOCATION]

Options:
-v, --verbose

Display more information.

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

--stacked-on=ARG
 

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

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

--stacked

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

--overwrite

Ignore differences between branches and overwrite unconditionally.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

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 be an unbound branch with no working tree.

--checkout

Reconfigure to be a bound branch with a working tree.

--lightweight-checkout
 

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

--standalone

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

--tree

Reconfigure to be an unbound branch with a working tree.

--use-shared

Reconfigure to use a shared repository.

Description:

A target configuration must be specified.

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

See also:

branches, checkouts, standalone-trees, working-trees

remerge

Purpose:

Redo a merge.

Usage:

bzr remerge [FILE...]

Options:
-v, --verbose

Display more information.

--reprocess

Reprocess to reduce spurious conflicts.

-q, --quiet

Only display errors and warnings.

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

Only remove files that have never been committed.

-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. bzr will delete them if they can easily be recovered using revert. If no options or parameters are given bzr will scan for files that are being tracked by bzr but missing in your tree and stop tracking them for you.

Aliases:

rm, del

remove-tree

Purpose:

Remove the working tree from a given branch/checkout.

Usage:

bzr remove-tree [LOCATION]

Options:
--force

Remove the working tree even if it has uncommitted changes.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

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

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

See also:

checkout, working-trees

renames

Purpose:

Show list of renamed files.

Usage:

bzr renames [DIR]

Options:
-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 submitting 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. "0.9": Bundle format 0.9, Merge Directive 1. "4": Bundle format 4, Merge Directive 2 (default).

--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 merge directive to this file; use - for stdout.

-m ARG, --message=ARG
 

Message string.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--no-patch

Do not include a preview patch in the merge directive.

-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 "claws", "evolution", "kmail", "mutt", and "thunderbird"; generic options are "default", "editor", "emacsclient", "mapi", and "xdg-email". Plugins may also add supported clients.

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

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

Merge directives are applied using the merge command or the pull command.

See also:

merge, pull

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

shelve

Purpose:

Temporarily set aside some changes from the current tree.

Usage:

bzr shelve [FILE...]

Options:
--all

Shelve all changes.

-v, --verbose

Display more information.

--list

List shelved changes.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-m ARG, --message=ARG
 

Message string.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

writer:
--plain

Plaintext diff output.

Description:

Shelve allows you to temporarily put changes you've made "on the shelf", ie. out of the way, until a later time when you can bring them back from the shelf with the 'unshelve' command.

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

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

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

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

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

See also:

unshelve

sign-my-commits

Purpose:

Sign all commits by a given committer.

Usage:

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

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

--no-pending

Don't show pending merges.

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

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

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

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

Aliases:

st, stat

See also:

diff, revert, status-flags

switch

Purpose:

Set the branch of a checkout and update.

Usage:

bzr switch TO_LOCATION

Options:
--force

Switch even if local commits will be lost.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

Description:

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

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

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

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

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

tag

Purpose:

Create, remove or modify a tag naming a revision.

Usage:

bzr tag TAG_NAME

Options:
--force

Replace existing tags.

-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch in which to place the tag.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

--delete

Delete this tag rather than placing it.

Description:

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

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

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

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

See also:

commit, tags

tags

Purpose:

List tags.

Usage:

bzr tags

Options:
--sort=ARG

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

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-d ARG, --directory=ARG
 

Branch whose tags should be displayed.

--show-ids

Show internal object ids.

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

-h, --help

Show help message.

Description:

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

See also:

tag

testament

Purpose:

Show testament (signing-form) of a revision.

Usage:

bzr testament [BRANCH]

Options:
-v, --verbose

Display more information.

-h, --help

Show help message.

-q, --quiet

Only display errors and warnings.

--long

Produce long-format testament.

--strict

Produce a strict-format testament.

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

--local

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

-r ARG, --revision=ARG
 

See "help revisionspec" for details.

Description:

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

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

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

See also:

commit

unshelve

Purpose:

Restore shelved changes.

Usage:

bzr unshelve [SHELF_ID]

Options:
-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

action:
--apply

Apply changes and remove from the shelf.

--delete-only

Delete changes without applying them.

--dry-run

Show changes, but do not apply or remove them.

Description:

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

See also:

shelve

update

Purpose:

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

Usage:

bzr update [DIR]

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

--1.6

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

--1.6.1-rich-root
 

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

--1.9

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

--1.9-rich-root
 

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

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

--development

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

--development-subtree
 

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

--development-wt5
 

A working-tree format that supports views and content filtering.

--development-wt5-rich-root
 

A variant of development-wt5 that supports rich-root data (needed for bzr-svn).

--dirstate

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

--dirstate-tags
 

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

--knit

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

--metaweave

Transitional format in 0.8. Slower than knit.

--pack-0.92

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

--rich-root

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

--rich-root-pack
 

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

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

Print just the version number.

-v, --verbose

Display more information.

-q, --quiet

Only display errors and warnings.

-h, --help

Show help message.

version-info

Purpose:

Show version information about this tree.

Usage:

bzr version-info [LOCATION]

Options:
--all

Include all possible information.

-v, --verbose

Display more information.

--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 (simple text) format (default).

Description:

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

For example:

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

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

  • {date} - date of the last revision

  • {build_date} - current date

  • {revno} - revision number

  • {revision_id} - revision id

  • {branch_nick} - branch nickname

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

    otherwise 1

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