BzrQuickStartForEmacsDevs

Bazaar quick start guide for Emacs Developers

Emacs now uses Bazaar as its version control system.

If you are an Emacs contributor without experience using Bazaar in particular and Distributed Version Control Systems (dVCS) in general, this document tells you how to use Bazaar in a simple, CVS-like way.

The “workflow” described in this document allows you to:

There is a separate document, BzrForEmacsDevs, that describes several workflows that take advantage of the fact that Bazaar is a distributed version control system. Such workflows are particularly useful if you are making substantial changes to Emacs.

Conventions and basic info

Starting

We start by telling Bazaar who you are. This is used for recording the author of the commits:

bzr whoami "Joe Hacker <joe.hacker@address.org>"

Now we create a shared repository. A repository is just a place where you can store one or more branches, not necessarily related one to each other. It’s a performance trick that dramatically improves (in terms of required time and storage) certain operations that you may do when you expand your Bazaar usage beyond what is explained here. It is a good idea, but not strictly required.

bzr init-repo --2a emacs/

creates a shared repository in the directory emacs. --2a is an storage format specification which is the most efficient and modern format supported by Bazaar right now and is the default on Bazaar version 2.0.

Now we get the source files plus all the history of the branch we work on (trunk on this case, which is the CVS mainline):

On Bazaar parlance this creates a bound branch, also known as a heavyweight checkout.

This is a slow process. It needs to download about 300 MB of data and makes heavy use of the CPU sometimes, so be patient.

Now we have everything we need in the directory trunk. If you are working inside a shared repository like recommended above do not move the trunk directory around nor rename it.

Daily work

It is fairly similar to CVS. If you’re using the command-line:

Optionally, before doing a commit, you can do bzr status to view the changed which will be committed by bzr commit (with no filename arguments) and unknown files which will be ignored by bzr commit. “Unknown” means that the file neither matches a pattern in .bzrignore nor is registered with Bazaar. Typically unknown files are newly added. In order to track changes in them, use the bzr add command:

bzr add new-file ...

then commit them as usual with the rest of the appropriate changeset. Warning: bzr add with no filename arguments will add everything in your tree that’s currently unknown. It is highly recommended to check what will be committed with bzr status after you do a “bare” add. Alternatively, just specify all files to add explicitly. You can also commit using VC-dir:

If Bazaar complains about conflicts after the update, fix them and use

bzr resolve <file>

(bzr resolve cannot fix any conflicts itself; it only marks a file as being ready to commit after you fix the conflicts.) You can list a series of name files after each command for restricting its scope. If omitted, all files are assumed, except in the case of bzr resolve, which requires the file names or the switch --all for marking all conflicts as resolved.

With Bazaar you shouldn’t commit the changed files one at a time if they belong to the same logical change. So please don’t do:

but instead do

or just

if those are the only changed files. (It is recommended to do a bzr status before a commit without filename arguments to check for inadvertant changes that would be committed.)

This is very important because every commit creates a changeset, which is a discrete step on the history of the code base. A changeset should correspond to one well-defined purpose which is completely achieved with the corresponding commit as, for instance, “Fix bug #342” or “Implement feature Foo”.

Before committing, not just the files you are committing but all your local source files must be up to date with upstream. So if somebody else commits to upstream between the bzr up and the bzr commit commands, you’ll need to bzr up again.

More branches

If you work on other branches besides trunk, just cd into your shared repository and

bzr checkout URL_TO_UPSTREAM_branch_name your_branch_name

(Note, get a list of branches by browsing http://bzr.savannah.gnu.org/r/emacs/ ; see BzrForEmacsDevs for more information.)

This is one of the operations where having a shared repository helps: Bazaar will download only those revisions which are not on trunk, so the process will be much faster.

Other commands

Bazaar has status, log, annotate, revert, etc. They do what you expect.

Use VC-Dir

VC-Dir works fine with this setup. It doesn’t support all features of more advanced Bazaar setups, though.

That's it

You know enough to continue your Emacs hacking. Furthermore, you have the initial elements for turning your current setup into a more advanced setup once you learn enough to do so. You will not need to download all the history from upstream again.

What you have, what you are missing

You have in your disk a copy of the VC history of the trunk branch since the last bzr update. Hence, Bazaar does not need to contact a server upstream for displaying logs, reverting edited files, annotating, etc. This is useful for working off-line. [I believe this is false; to work offline you need to unbind the branch, at least if Bazaar can reach the Internet. Unbinding has some unintuitive consequences; be careful.]

Bazaar makes possible to commit changes off-line to your local history and send them upstream in one batch. There are several options with associated trade-offs for doing this, so read BzrForEmacsDevs or ask on the emacs-devel mailing list if you are interested on that possibility.

Bazaar allows you to work as if you had your own personal CVS branch in your machine and communicate changes with other developers, not only with upstream. What’s considered “upstream” is just an agreement among the developers who participate on the same project. That is the essence of Distributed Version Control. Your current setup can be easily adapted for this, but you need to master the necessary Bazaar concepts before embarking on that practices.

Bazaar makes it very easy to create as many private branches as you wish.

Further reading

BzrForEmacsDevs

Comments

At present, ubuntu jaunty’s bzr package installs version 1.13, and this “quick” start guide requires 1.17 and strongly recommends 2.0. So to get started quickly, I’m also supposed to build my own bzr from scratch, right? – Doom