To use Bazaar you need to understand four core concepts:
Let’s look at each in more detail.
A revision is a snapshot of the state of a tree of files and directories, including their content and shape. A revision also has some metadata associated with it, including:
Revisions are immutable and can be globally, uniquely identified by a revision-id. An example revision-id is:
Revision-ids are generated at commit time or, for imports from other systems, at the time of import. While revision-ids are necessary for internal use and external tool integration, branch-specific revision numbers are the preferred interface for humans.
Revision numbers are dotted decimal identifiers like 1, 42 and 2977.1.59 that trace a path through the revision number graph for a branch. Revision numbers are generally shorter than revision-ids and, within a single branch, can be compared with each other to get a sense of their relationship. For example, revision 10 is the mainline (see below) revision immediately after revision 9. Revision numbers are generated on the fly when commands are executing, because they depend on which revision is the tip (i.e. most recent revision) in the branch.
See Specifying revisions in the appendices for a closer look at the numerous ways that revisions and ranges of revisions can be specified in Bazaar, and Understanding Revision Numbers for a more detailed description of revision numbering.
A working tree is a version-controlled directory holding files the user can edit. A working tree is associated with a branch.
Many commands use the working tree as their context, e.g. commit makes a new revision using the current content of files in the working tree.
In the simplest case, a branch is an ordered series of revisions. The last revision is known as the tip.
Branches may split apart and be merged back together, forming a graph of revisions. Technically, the graph shows directed relationships (between parent and child revisions) and there are no loops, so you may hear some people refer to it as a directed acyclic graph or DAG.
If this name sounds scary, don’t worry. The important things to remember are:
A repository is simply a store of revisions. In the simplest case, each branch has its own repository. In other cases, it makes sense for branches to share a repository in order to optimize disk usage.
Once you have grasped the concepts above, the various ways of using Bazaar should become easier to understand. The simplest way of using Bazaar is to use a standalone tree, which has a working tree, branch, and repository all in a single location. Other common scenarios include:
The best way to use Bazaar, however, depends on your needs. Let’s take a look at some common workflows next.