This chapter will explain and demonstrate, with examples, the basic version control operations using Bazaar in the simplest possible scenario—working solo on a single branch. Although the scenario is simple, the operations you will learn here are the very core functionality of version control, and will remain relevant throughout your experience with Bazaar, even in more complex setups with multiple collaborators and branches.
The main topics in this chapter are as follows:
- Introducing the command-line interface and Bazaar Explorer
- First-time setup—configuring the author setting
- Performing the basic version control operations
- Beyond the basics—performing other practical operations
Before diving into Bazaar, it is essential to understand its four core concepts:
- Revision: This is a snapshot of the project's files
- Repository: This is a store of revisions recorded in the project
- Branch: This is an ordering of revisions – a history
- Working tree: This is a directory tree in your filesystem, which contains your files and subdirectories associated with a branch and a revision
These concepts are central to Bazaar and appear everywhere in the documentation. Therefore, it is crucial to understand them well.
A revision is a snapshot of the tree of files and directories in a project recorded at some specific point in time. As you make changes to the files in the project, you record a new snapshot, which is a new revision. In this way, the revisions will represent logical steps forward in the evolution of the project. Recording a revision is called committing. In addition to the state of the project, a revision contains metadata such as:
In Bazaar, revisions on a linear timeline (on a single branch) are numbered with an integer sequence starting from 1, and incremented by one for each new revision recorded.
The following is an example of a commit log, which shows the aforementioned metadata and revisions numbers:
When working on multiple branches, the timeline becomes non-linear and a dotted notation is used. This will be explained later, but to give you an idea, the following is an example of a commit log with multiple branches:
A repository is simply a store of revisions. The content and metadata of revisions are stored inside a repository in a compact and efficient way. Often, the total size of the repository, including all revisions, is smaller than the total size of all the files of the latest revision in an uncompressed form:
A branch represents the ordering of revisions; in other words, how the revisions follow each other in the history.
Each revision contains a reference to its parent revision, or multiple references if there are multiple parents, as is the case when a revision is created by the merging of two or more other revisions. A branch has precisely one latest revision, called the tip. By following the parent relationships from the tip, revisions form a directed acyclic graph, representing the ordering of revisions within the branch.
A working tree is associated with a branch. It contains the files and subdirectories of the project at a specific revision of the branch. It looks and behaves exactly like any other regular directory in the filesystem. In addition to the project's files, a working tree contains a hidden subdirectory named .bzr, which is used by Bazaar to track the state of the project's files relative to the associated revision.
To illustrate with an example—at the left is a regular directory, and at the right is the same directory converted to a working tree. The only difference is the presence of a hidden .bzr directory:
A working tree can be set to any revision of its associated branch, effectively resetting its content to the files and subdirectories as they existed at the given revision. In this way, you can browse the content of the project at any past revision.
The most common use of the working tree is to view the project's files at the latest revision of the branch, so that you can work with those files—edit their content, add new files, or delete them. At any time, you can either revert some or all of your pending changes to their original state (of the last revision), or commit your changes to record the current state as a new revision of the project:
When you work with a project under version control, you will use all of these concepts together, as follows:
- You use a working tree to access and modify the files of your project. The working tree looks and behaves like any other ordinary directory in your filesystem, with an added hidden
.bzrdirectory to store Bazaar's files. - The working tree is linked to a Bazaar branch, which in turn is linked to a Bazaar repository. The branch represents the order in which revisions are recorded, and the repository stores the content of revisions as snapshots in a compressed form.
- As you make changes in the working tree and record them as a new revision, the content of the revision is added to the repository as a new snapshot, and the branch tip is updated to point to the new revision.
The four core concepts are vital in most version control operations. Therefore, it is good to understand what they are and how they are linked together.
Bazaar stores its files in one or more hidden .bzr directories, depending upon the configuration.
In this chapter, we will focus on the most simple configuration, where the working tree data, the branch data, and the repository data are all stored in a single hidden .bzr directory in the working tree, as follows:
/path/to/working/tree/.bzr |-- branch # branch data (ordering of revisions) |-- checkout # working tree data (track pending changes) |-- repository # repository data (content of revisions)
This configuration is called a standalone tree.
Just to give you an alternative example, another common configuration is the
shared repository, which will be explained in the next chapter. In this configuration, the repository data is stored in a .bzr directory at a higher level, as follows:
/path/to/shared/repo/ |-- .bzr | |-- repository # repository data |-- some_branch | |-- ... # project files in the working tree | |-- .bzr # hidden .bzr directory | |-- checkout # working tree data | |-- branch # branch data |-- another_branch | |-- ... # project files in the working tree | |-- .bzr # hidden .bzr directory |-- checkout # working tree data | |-- branch # branch data |-- yet_another_branch | |-- ...
In this configuration, there are multiple working trees, each in a separate subdirectory, corresponding to different branches. The .bzr directory of each working tree contains the working tree data and the branch data, but not the repository data. The repository data is stored in the .bzr directory of the parent directory. In this setup, the repository data is shared by the branches.
Throughout the book, we will explain various configurations and their practical use cases in detail. For now, it is enough just to be aware that the working tree data, the branch data, and the repository data may be stored at different locations depending upon the use case.