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.
