Small guide for the use of Bazaar-NG
(by Damien Caliste)

Simple usage of bzr

This little help file is intended for user having a 0.9 version at least. A very well done tutorial is reachable at this location.

First use of bzr

To use bazaar, one must identify himself or herself. This is simply done using e.g.:

How to get a local copy from the shared branches?

The public files of the project are stored on a server machine which address is archives.abinit.org. You must have a ssh access to this machine to retrieve files. As an example, let's say that the branch maintained by Caliste at version 0.2 is desired, to get it type:

After that, a local copy of the files are located on our disk in the directory localDir. One can begin to work on it, modifying files, adding files...

I've done some modifications on my local copy, what do I do?

Before publishing our modifications, we need to know exactly what they are by asking bzr what have been done:

It can return something like this:

unknown:
  .bzrignore
  doc/Makefile.am
  lib/MPIfake.f90@
  src/input_wf_diag.f90
  utils/Makefile.am
  utils/PSPfiles/Makefile.am
modified:
  Makefile.am
  configure.ac
  lib/module_bigdft.f90.in
  src/Makefile.am
  src/common_routines.f90

Reading it, we see that several files are not version controlled in different directories (labelled unknown) and some other have been modified. If we consider that unknown files are relevant for publishing and should be communicated to other members, we must add them calling:

Then we must locally store our changes using:

The message argument is very important, since it is what will be read by other members when receiving the modifications. Finally, we're happy enough with our changes and like to publish them on the server. To do it we call (in the case that we were Caliste working on the version 0.2):

Advanced usage of bzr

One should write something here.

Migration from baz to bzr

Running the transition script

It first requires some tools, packaged with bzrtools and pybaz. A good description about downloading and using these tools is given on this page. Before calling the transformation tool, one must adapt the baz.py script to correct a small mistake. When the command baz categories is called, the archive is given with a --archive option, which is incorrect. One must remove this --archive option in the file pybaz/backends/baz.py line 372. Then, runing:

will create the shared branches monitored by bzr. For more informations about shared branches, see this page. It is quite specialised, so read it when bzr basic concepts have already been learned.

Some remarks on bzr and differences with baz

Some unordered remarks about migrating baz repositories to shared branches managed by bzr.

• The one level tree structure used in baz is changed for a full directory structure. For instance, the old branch bigdf-devel--caliste--0.2 becomes bigdft-devel/0.2/caliste.
• The permissions on each branch are lost.
• The history and control version machinery is stored in a .bzr directory located in the root directory of the new shared branches. To be able to push modifications in this new shared branches, some write access must be granted in this .bzr directory. The following files and directories are concerned:
  • .bzr/repository/lock (directory) ;
  • .bzr/repository/knits (directory) ;
  • .bzr/repository/inventory.* (files) ;
  • .bzr/repository/revisions.* (files).
• All .arch-inventory files are not migrated and should be replaced by a single file located in the root directory of a branch called .bzrignore. The syntax of this file is trivial, using simple matching patterns on each line. Here is an example:

  tmp
  Makefile.in
  Makefile
  aclocal.m4
  autom4te.cache
  config/*
  configure
  

• There is no equivalent for baz abrowse. One should advice to use a sftp browser instead (like Konqueror), or to use the bzrtools package and type something like: bzr branches sftp://archives.abinit.org/bigdft/bzr which returns:

  bigdft-devel/0.1/caliste
  bigdft-devel/0.1/genovese
  bigdft-devel/0.1/merge
  bigdft-devel/0.2/caliste
  bigdft-devel/0.2/deutsch
  bigdft-devel/0.2/genovese
  bigdft-devel/0.2/goedecker
  bigdft-devel/0.2/piwonski
  bigdft-devel/0.2/rayson
  

• I don't know how to monitor what patch has been submitted to which branch as baz abrowse did it.
• Maybe the most important concern, but I'm not sure I'm right, is that even if history is kept (all changelogs are still attach to all branches), the merging history seems to have been lost in the migration.