Bazaar for Mercurial users

How Bazaar feels the same

Bazaar and Mercurial are both distributed version control systems, and so both provide each user with their own version of the code that is standalone, allowing them to work independently of anyone else, and then merge the changes at a later date.

The basic command sets of Bazaar and Mercurial are similar, but there are subtle differences to be aware of.

How Bazaar feels different

While the fundamental units in both Mercurial (the clone) and Bazaar (the branch) are similar, there are fundamental differences. Mercurial clones are completely standalone, and can be located anywhere in the filesystem, Bazaar has the concept of a repository (a directory in which revisions and branches are stored). For efficient use, it is generally recommended that all Bazaar branches are located in the repository directory. (Terminology is also somewhat confusing - a Mercurial “repository” is equivalent to a Bazaar “branch”, and Mercurial has no equivalent to a Bazaar “repository”).

Bazaar has no equivalent of Mercurial’s (named or unnamed) branches - all branches in Bazaar are located in distinct filesystem directories. In particular, merging is between branches - the normal Mercurial working practice of pulling in changes (creating a new head) and then merging within a single repository is done differently in Bazaar.

Core tasks

Getting help on a command

Bazaar has a help command with extensive help on the various subcommands, much like Mercurial:

$ bzr help
$ bzr help init

Create a new project

To create a standalone branch looks very similar to Mercurial:

$ bzr init myproject

However, to create the recommended Bazaar repository/branch structure is slightly more complex:

$ bzr init-repo myproject
$ cd myproject
$ bzr init trunk

Clone a repository

Creating a copy of a branch (whether a clone of a remote branch, or a branch of a local one) is similar to Mercurial, but using the branch command rather than clone:

$ bzr branch trunk feature-a

Bazaar has an alias of clone which is the same as branch, so things still work even if you forget the correct Bazaar term!

Updating a local branch from upstream

To get changes from another branch, Bazaar uses the pull command in much the same way as Mercurial:

$ bzr pull upstream

As with Mercurial, the default is to pull from “the place you branched from”.

Unlike Mercurial, however, it is not possible to pull from a branch with divergent changes (a situation which would create multiple heads in Mercurial). Rather, the pull fails and it is necessary to use the merge command:

$ bzr merge upstream
$ bzr conflicts
[ shows conflicts ]
$ vi a
$ bzr resolve a
[ marks the conflict in a as resolved ]
$ bzr commit -m "Merged from upstream"

In Bazaar, the recommended practice is this:

  1. Keep trunk as a mirror of upstream and keep it up to date using pull.

  2. Develop changes in a feature branch. To keep a feature branch up to date:

    $ bzr merge ../trunk
    [ resolve conflicts ]
    $ bzr commit -m "Merge trunk rev xyz"
  3. When the feature branch is ready to land, merge it back into trunk:

    $ cd ../trunk
    $ bzr merge ../feature-a
    [ resolve conflicts ]
    [ run tests ]
    $ bzr commit -m "Land feature-x"

If trunk is bound to upstream, then the commit will implicitly propagate the change upstream. Otherwise, you’ll need to push it.

Seeing how the working tree has changed

Checking how the working tree has been changed uses the bzr status and bzr diff commands, just like Mercurial:

$ bzr status
$ bzr diff

Committing your work

To commit your work to the local repository, you use the commit command, just as in Mercurial:

$ bzr commit

Sending changes upstream uses the push and pull commands, again just as in Mercurial.

Network protocols

Bazaar offers more protocols than Mercurial:

$ bzr help urlspec
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).

Unlike Mercurial, however, there is no read/write HTTP protocol built in. Rather, Bazaar has a built in Bazaar “smart server” which serves data using the custom “bzr” protocol.

For read/write access over HTTP in Bazaar, try the webdav plugin.

Revisions

Bazaar identifies revisions using a unique “revision ID”, where Mercurial uses changeset hashes. Both systems allow use of a local revision number. Bazaar has a richer system of revision specifiers (the most significant of which is date-based, many of the others appear to be expressible in Mercurial). Full details can be obtained using:

$ bzr help revisionspec

Note also that revision numbers are assigned differently by Mercurial and Bazaar. In Mercurial, revision numbers are based on when a revision is added to a given repository. In Bazaar, revision numbers are calculated:

  • Revisions on the left-hand side of the revision graph as assigned increasing integers.
  • Merged revisions have dotted revision numbers based on where that line of development started from.

This is illustrated in our graphical log viewer (qlog) below.

../_images/dialog-log.png

These differences can be both a positive and a negative:

  • The upside is that different users mirroring an upstream branch will see exactly the same revision numbers, regardless of which order those revisions first arrived in their repository.
  • The downside is that the common practice (for hg/git users) of “merge upstream into feature branch then push upstream” will make the upstream a mirror of your feature branch, changing the upstream revision numbers and most likely annoying other contributors.

The solution is simple: do not push from a feature branch to upstream. As explained earlier, the right process in Bazaar is to keep a trunk branch that mirrors upstream and merge your feature branch into that instead.

For more information on organizing branches and how Bazaar assigns revision numbers, see Bazaar Zen.

Other commands

Extensions

Bazaar has a rich set of “plugins” available, comparable to Mercurial’s extension system. Bazaar plugins offer features similar to Mercurial Queues (loom) as well as direct interfaces to foreign version control systems (for example, bzr-svn).

Notes

Alternative Workflows

Bazaar has a number of commands and concepts designed specifically to support alternative workflows. For example, “bound branches” and “checkouts” support certain aspects of a centralised workflow. Mercurial has nothing comparable - workflow is defined by local policy in Mercurial, rather than by explicit tool support.

Display of Revisions

The default display of revisions in bzr log is designed to emphasize the mainline flow of changes. Specifically, only the “top level” of revisions is shown by default, so that a branch, plus subsequent changes, plus a final merge, is shown simply as the final merge.

This is in direct contrast to Mercurial, where all revisions are shown, and merges are frequently committed with a simple message such as “Merge from xxx”. Such merge messages can be confusing in Bazaar given all of the detail/context is hidden by default.

In Bazaar, it’s important to make your final merge message something meaningful on its own, e.g.:

"Land new feature X, fixing bug Y while we're at it"

While hidden by default, it’s easy to see merged revisions:

  • In the GUI, click on the “+” symbols in the revision graph.
  • On the command line, use either bzr log --include-merges or bzr log -n0. (The -n option lets you specify a depth and a depth of 0 means all levels.)

If you want revisions always shown by default on the command line, add this to your bazaar.conf file:

[ALIASES]
log=log --include-merges

Feedback and edits

See Improving these documents.