Bazaar User Reference

Version: 0.90.0
Generated:2007-08-31

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

Checkouts

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

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

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

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

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

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

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

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

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

Related commands:

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

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.

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

Bug Trackers

Bazaar provides the ability to store information about bugs being fixed as metadata on a revision.

For each bug marked as fixed, an entry is included in the 'bugs' revision property stating '<url> <status>'.

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.

Files

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

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

A typical config file might look something like:

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

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

Storage Formats

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

dirstate:(native) (default) New in 0.15: Fast local operations. Compatible with bzr 0.8 and above when accessed over the network.
dirstate-tags:(native) New in 0.15: Fast local operations and improved scaling for network operations. Additionally adds support for tags. Incompatible with bzr < 0.15.
knit:(native) Format using knits. Recommended for interoperation with bzr <= 0.14.

Deprecated formats are shown below.

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

Global Options

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

--quiet Suppress informational output; only print errors and warnings
--version Print the version number
--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
-Derror Instead of normal error handling, always print a traceback on error.
--profile Profile execution using the hotshot profiler
--lsprof Profile execution using the lsprof profiler
--lsprof-file Profile execution using the lsprof profiler, and write the results to a specified file. If the filename ends with ".txt", text format will be used. If the filename either starts with "callgrind.out" or end with ".callgrind", the output will be formatted for use with KCacheGrind. Otherwise, the output will be a pickle.

See doc/developers/profiling.txt for more information on profiling.

Note: --version must be supplied before any command.

Revision Identifiers

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

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

Further details are given below.

revno:

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

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

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

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

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

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

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

Examples:

before:1913    -> Return the parent of revno 1913 (revno 1912)
before:revid:aaaa@bbbb-1234567890  -> return the parent of revision
                                      aaaa@bbbb-1234567890
bzr diff -r before:revid:aaaa..revid:aaaa
      -> Find the changes between revision 'aaaa' and its parent.
         (what changes did 'aaaa' introduce)
tag:

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

date:

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

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

bzr log -r date:yesterday..-1

Examples:

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

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

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

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

Examples:

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

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

Examples:

branch:/path/to/branch
submit:

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

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

Examples:

$ bzr diff -r submit:

Status Flags

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

xxx   <filename>

where the columns' meanings are as follows.

Column 1 - versioning/renames:

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

Column 2 - contents:

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

Column 3 - execute:

* The execute bit was changed

URL Identifiers

Supported URL prefixes:

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

Commands

add

Purpose:

Add specified files or directories.

Usage:

bzr add [FILE...]

Options:
--file-ids-from=ARG
 

Lookup file ids from this tree.

--no-recurse

Don't recursively add the contents of directories.

--dry-run

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

-h, --help

Show help message.

-v, --verbose

Display more information.

Description:

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

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

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

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

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

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

See also:

remove

annotate

Purpose:

Show the origin of each line in a file.

Usage:

bzr annotate FILENAME

Options:
--show-ids

Show internal object ids.

--all

Show annotations on all lines.

-h, --help

Show help message.

--long

Show commit date in annotations.

-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:
-h, --help

Show help message.

Description:

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

See also:

checkouts, unbind

branch

Purpose:

Create a new copy of a branch.

Usage:

bzr branch FROM_LOCATION [TO_LOCATION]

Options:
-h, --help

Show help message.

-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:
-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:
-h, --help

Show help message.

--name-from-revision
 

The path name in the old tree.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

Description:

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

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

See also:

ls

check

Purpose:

Validate consistency of branch history.

Usage:

bzr check [BRANCH]

Options:
-h, --help

Show help message.

-v, --verbose

Display more information.

Description:

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

See also:

reconcile

checkout

Purpose:

Create a new checkout of an existing branch.

Usage:

bzr checkout [BRANCH_LOCATION] [TO_LOCATION]

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

-h, --help

Show help message.

-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:
-h, --help

Show help message.

--unchanged

Commit even if nothing has changed.

--fixes=ARG

Mark a bug as being fixed by this revision.

--strict

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

-F MSGFILE, --file=MSGFILE
 

Take commit message from this file.

-m ARG, --message=ARG
 

Description of the new revision.

--local

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

-v, --verbose

Display more information.

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.

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.

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

-h, --help

Show help message.

See also:

ls, status

diff

Purpose:

Show differences in the working tree or between revisions.

Usage:

bzr diff [FILE...]

Options:
-p ARG, --prefix=ARG
 

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

--diff-options=ARG
 

Pass these options to the external diff program.

-h, --help

Show help message.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

Description:

If files are listed, only the changes in those files are listed. Otherwise, all changes for the tree are listed.

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

Examples:

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

bzr diff

Difference between the working tree and revision 1:

bzr diff -r1

Difference between revision 2 and revision 1:

bzr diff -r1..2

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

bzr diff --prefix old/:new/

Show the differences between the two working trees:

bzr diff bzr.mine bzr.dev

Show just the differences for 'foo.c':

bzr diff foo.c
Aliases:

di, dif

See also:

status

export

Purpose:

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

Usage:

bzr export DEST [BRANCH]

Options:
-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

--root=ARG

Name of the root directory inside the exported file.

-h, --help

Show help message.

--format=ARG

Type of file to export to.

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:
-h, --help

Show help message.

--long

Show help on all commands.

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.

-h, --help

Show help message.

Description:

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

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

Ignore patterns specifying absolute paths are not allowed.

Ignore patterns may include globbing wildcards such as:

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

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

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

Examples:

Ignore the top level Makefile:

bzr ignore ./Makefile

Ignore class files in all directories:

bzr ignore '*.class'

Ignore .o files under the lib directory:

bzr ignore 'lib/**/*.o'

Ignore .o files under the lib directory:

bzr ignore 'RE:lib/.*\.o'
See also:

ignored, status

ignored

Purpose:

List ignored files and the patterns that matched them.

Usage:

bzr ignored

Options:
-h, --help

Show help message.

See also:

ignore

info

Purpose:

Show information about a working tree, branch or repository.

Usage:

bzr info [LOCATION]

Options:
-h, --help

Show help message.

-v, --verbose

Display more information.

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

-h, --help

Show help message.

Branch Format:
--format=ARG

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

--default

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

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

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

-h, --help

Show help message.

Repository format:
--format=ARG

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

--default

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

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

--weave

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

Description:

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

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

Examples:

Create a shared repositories holding just branches:

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

Make a lightweight checkout elsewhere:

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

init-repo

See also:

branch, checkout, init, repositories

log

Purpose:

Show log of a branch, file, or directory.

Usage:

bzr log [LOCATION]

Options:
-v, --verbose

Show files changed in each revision.

-h, --help

Show help message.

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

-m ARG, --message=ARG
 

Show revisions whose message matches this regular expression.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

Log format:
--log-format=ARG
 

Use specified log format.

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

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

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

Examples:

Log the current branch:

bzr log

Log a file:

bzr log foo.c

Log the last 10 revisions of a branch:

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

ls

Purpose:

List files in a tree.

Usage:

bzr ls [PATH]

Options:
--from-root

Print paths relative to the root of the branch.

--ignored

Print ignored files.

--kind=ARG

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

-v, --verbose

Display more information.

-h, --help

Show help message.

--versioned

Print versioned files.

--unknown

Print unknown files.

--non-recursive
 

Don't recurse into subdirectories.

--show-ids

Show internal object ids.

--null

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

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

See also:

cat, status

merge

Purpose:

Perform a three-way merge.

Usage:

bzr merge [BRANCH]

Options:
--pull

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

--force

Merge even if the destination tree has uncommitted changes.

--remember

Remember the specified location as a default.

--reprocess

Reprocess to reduce spurious conflicts.

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

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

-h, --help

Show help message.

Merge algorithm:
--merge-type=ARG
 

Select a particular merge algorithm.

--diff3

Merge using external diff3

--merge3

Native diff3-style merge

--weave

Weave-based merge

Description:

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

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

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

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

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

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

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

Examples:

To merge the latest revision from bzr.dev:

bzr merge ../bzr.dev

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

bzr merge -r 82 ../bzr.dev

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

bzr merge -r 81..82 ../bzr.dev
See also:

remerge, status-flags, update

missing

Purpose:

Show unmerged/unpulled revisions between two branches.

Usage:

bzr missing [OTHER_BRANCH]

Options:
-h, --help

Show help message.

--this

Same as --mine-only.

--other

Same as --theirs-only.

--mine-only

Display changes in the local branch only.

-v, --verbose

Display more information.

--show-ids

Show internal object ids.

--theirs-only

Display changes in the remote branch only.

--reverse

Reverse the order of revisions.

Log format:
--log-format=ARG
 

Use specified log format.

--line

Log format with one line per revision

--long

Detailed log format

--short

Moderately short log format

Description:

OTHER_BRANCH may be local or remote.

See also:

merge, pull

mkdir

Purpose:

Create a new versioned directory.

Usage:

bzr mkdir DIR...

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

-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:
-h, --help

Show help message.

Description:

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

See also:

info

pack

Purpose:

Compress the data within a repository.

Usage:

bzr pack [BRANCH_OR_REPO]

Options:
-h, --help

Show help message.

See also:

repositories

plugins

Purpose:

List the installed plugins.

Usage:

bzr plugins

Options:
-h, --help

Show help message.

Description:

This command displays the list of installed plugins including the path where each one is located and a short description of each.

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

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

pull

Purpose:

Turn this branch into a mirror of another branch.

Usage:

bzr pull [LOCATION]

Options:
-v, --verbose

Display more information.

--remember

Remember the specified location as a default.

-h, --help

Show help message.

-d ARG, --directory=ARG
 

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

--overwrite

Ignore differences between branches and overwrite unconditionally.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

Description:

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

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

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

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

See also:

push, status-flags, update

push

Purpose:

Update a mirror of this branch.

Usage:

bzr push [LOCATION]

Options:
-v, --verbose

Display more information.

--create-prefix
 

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

--remember

Remember the specified location as a default.

--use-existing-dir
 

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

-d ARG, --directory=ARG
 

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

--overwrite

Ignore differences between branches and overwrite unconditionally.

-h, --help

Show help message.

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

remerge

Purpose:

Redo a merge.

Usage:

bzr remerge [FILE...]

Options:
--reprocess

Reprocess to reduce spurious conflicts.

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

--merge3

Native diff3-style merge

--weave

Weave-based merge

Description:

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

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

Examples:

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

bzr remerge --show-base

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

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

remove

Purpose:

Remove files or directories.

Usage:

bzr remove [FILE...]

Options:
--new

Remove newly-added files.

-h, --help

Show help message.

-v, --verbose

Display more information.

Deletion Strategy:
--force

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

--keep

Don't delete any files.

--safe

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

Description:

This makes bzr stop tracking changes to the specified files and delete them if they can easily be recovered using revert.

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

Aliases:

rm

remove-tree

Purpose:

Remove the working tree from a given branch/checkout.

Usage:

bzr remove-tree [LOCATION]

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

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

Do not save backups of reverted files.

-h, --help

Show help message.

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

See also:

cat, export

revno

Purpose:

Show current revision number.

Usage:

bzr revno [LOCATION]

Options:
-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:
-h, --help

Show help message.

Description:

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

send

Purpose:

Create a merge-directive for submiting changes.

Usage:

bzr send [SUBMIT_BRANCH] [PUBLIC_BRANCH]

Options:
-f ARG, --from=ARG
 

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

-h, --help

Show help message.

--format=ARG

Use the specified output format.

--no-bundle

Do not include a bundle in the merge directive.

-o ARG, --output=ARG
 

Write directive to this file.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

--no-patch

Do not include a preview patch in the merge directive.

--remember

Remember submit and public branch.

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.

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

See also:

merge

serve

Purpose:

Run the bzr server.

Usage:

bzr serve

Options:
--directory=ARG
 

Serve contents of this directory.

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

-h, --help

Show help message.

--inet

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

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

Aliases:

server

sign-my-commits

Purpose:

Sign all commits by a given committer.

Usage:

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

Options:
--dry-run

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

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

status

Purpose:

Display status summary.

Usage:

bzr status [FILE...]

Options:
--show-ids

Show internal object ids.

--short

Give short SVN-style status lines.

-h, --help

Show help message.

--versioned

Only show versioned files.

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

--short gives a status flags for each item, similar to the SVN's status command.

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

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

Aliases:

st, stat

See also:

diff, revert, status-flags

tag

Purpose:

Create, remove or modify a tag naming a revision.

Usage:

bzr tag TAG_NAME

Options:
-d ARG, --directory=ARG
 

Branch in which to place the tag.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

--force

Replace existing tags.

-h, --help

Show help message.

--delete

Delete this tag rather than placing it.

Description:

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

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

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

See also:

commit, tags

tags

Purpose:

List tags.

Usage:

bzr tags

Options:
-d ARG, --directory=ARG
 

Branch whose tags should be displayed.

-h, --help

Show help message.

Description:

This tag 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:
--strict

Produce a strict-format testament.

-h, --help

Show help message.

--long

Produce long-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:
-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:
--force

Say yes to all questions.

-r ARG, --revision=ARG
 

See 'help revisionspec' for details.

--dry-run

Don't actually make changes.

-h, --help

Show help message.

-v, --verbose

Display more information.

Description:

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

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

See also:

commit

update

Purpose:

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

Usage:

bzr update [DIR]

Options:
-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:
-h, --help

Show help message.

Branch format:
--format=ARG

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

--default

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

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

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

-h, --help

Show help message.

--check-clean

Check if tree is clean.

--include-history
 

Include the revision-history.

--format=ARG

Select the output format.

--include-file-revisions
 

Include the last revision for each file.

whoami

Purpose:

Show or set bzr user id.

Usage:

bzr whoami [NAME]

Options:
-h, --help

Show help message.

--branch

Set identity for the current branch instead of globally.

--email

Display email address only.

Examples:

Show the email of the current user:

bzr whoami --email

Set the current user:

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