The Bazaar Distributed Version Control System (DVCS)

Install Bazaar

This is the only version control system we are using. The stable version is available for all platforms on ​http://bazaar-vcs.org/Download. Use the latest version 1.X available for your platform. We’ll switch to 2.X later. There are no big differences anyway, but everybody has to have version 2.X to move to the new repository format, and binaries are not yet distributed for all platforms.

Tell Bazaar who you are by typing

bzr whoami "John Doe <john.doe@gmail.com>"

in a command line.

Learn Bazaar

Ideally, everybody should read ​http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html (or at least use it as a reference).

Alternatively, a minimal tutorial can be found here: ​http://doc.bazaar-vcs.org/bzr.dev/en/mini-tutorial/index.html

For reference: ​http://doc.bazaar-vcs.org/bzr.dev/en/user-reference/bzr_man.html

A very useful small PDF reference card to leave on your desk: ​http://doc.bazaar-vcs.org/bzr.dev/_static/en/quick-reference/bzr-quick-reference.pdf

Mini How-to, Bazaar in a command line

WARNING: even if you use Eclipse, learning a minimum of Bazaar in the command line is VERY important (some command are not available from Eclipse, and the Bazaar plugin is not always very stable)

To use Bazaar you need to understand four core concepts:

• Revision - a snapshot of the files you're working with. Each revision has a unique revision number. All files have the same revision number.
• Working tree - the directory containing your version-controlled files and sub-directories.
• Branch - an ordered set of revisions that describe the history of a set of files.
• Repository - a store of revisions.

First, create a new local repository (set of branches) and create a mirror branch inside (a pristine copy of the central branch):

bzr init-repo MADGRAPH --format=1.14

cd MADGRAPH

bzr branch lp:madgraph5/trunk 

We use the 1.14 format which is the "old" bazaar format everybody can use, whatever his/her version of bazaar. This can be changed in the future.

Now, create a local task branch (a linked copy of the mirror branch, where you actually work)

bzr branch trunk fix-123

cd fix-123

In principle, it’s not forbidden to work directly in the mirror branch, but this should be avoided for important modifications.

Here is a typical development cycle inside fix-123 (only local, and as many as you want!):

(hack some files)

bzr commit

(hack some files, you can add new ones with bzr add)

bzr status (to see a summary of what has been done since last commit)

bzr diff (to see what has been actually changed)

bzr log (to see the history of the branch)

bzr commit

...

Sometimes, you might want to refresh the mirror branch:

cd ../trunk

bzr pull

And you might also want to merge the latest trunk into the task branch

cd fix-123

bzr merge ../trunk

(resolve conflicts)

bzr commit -m “merged trunk”

At some point, you might want to distribute your local task branch to collaborate with other people. Try

bzr push lp:~madteam/madgraph5/mybranch

from your local branch directory (you can also use your local directory with ~myname instead of ~madteam). Then, all instructions above apply for people starting from mybranch instead of trunk (that’s the real magic of distributed VCS)! Note that this branch will belong to the “madteam”. You can also replace “madteam” by your Launchpad login to create a personal branch. There are also project branches (same level as trunk), but those should be reserved for long term parallel development (a.k.a. “series” in the Launchpad jargon), and their creation should be approved by the whole team.

Finally, once you think your branch can be merged to the main trunk (you need to have write access to the trunk):

cd trunk

bzr pull

bzr merge ../fix-123

(resolve conflicts)

bzr commit -m “Fixed bug #123”

RUN TESTS

bzr push

More evolved things with Bazaar

Resolve

The “resolve conflicts” step is particularly sensible, but things are rather simple with bazaar. If it finds possible conflicts in file foo (i.e. there is a modification in the trunk incompatible with a modification in the task branch), it will create automatically four files:

• foo: your file with merge markers
• foo.BASE: the state the file was in when you started working on it
• foo.THIS: your changes to the file
• foo.OTHER: the changes done to the file while you were working on it

you can diff all those files (e.g. using the compare tool in Eclipse) to understand what’s going on, and then simply edit the file foo, choose the changes that you want and remove the merge markers. Then you have to tell bazaar you are done by typing

bzr resolve foo

Bazaar will detect your fix and remove the BASE/THIS/OTHER files.

Send

If an EXTERNAL user work on a local private branch (using exactly the same tool as us), at the very end, he/she (of course) cannot do a push to the trunk. Instead, he would do

bzr send -o ../fix-123.patch

This patch can be sent to us by email, used later as a branch (e.g. bzr merge fix-123.patch) and is compatible with the standard linux patch format.

Undoing mistakes

Undoing changes since the last commit (everything will be lost!):

bzr status

bzr revert (name_of_a_file)

You can specify an older revision number with “-r 19” (go back to revision 19), or even “-r -2” (go back two revisions)

Undoing last commit:

bzr uncommit

Removing a file/dir

bzr remove foo (--keep if you just want to remove versionning info)

If a file is removed from the disk, commit will considered it as removed anyway

Export

Sometimes, you might want to export your branch as a tar.gz (for official releases, communication with external beta testers, ...)

bzr commit

bzr tag version-1.5 (not necessary but useful to come back to that version later with -r tag:version-1.5)

bzr export ../madgraph-1.5.tar.gz

Bazaar will take care of everything for you (remove versioning info, creating the tar.gz, ...)

Working centralized (with checkout, bind, update, ...)

NO WAY!!!! we do not encourage (at first) this way of working, even if Bazaar supports it. So forget about those commands.