Quick Bazaar tutorial

From Yade

Revision as of 14:39, 28 September 2010 by Jduriez (talk | contribs)

Bazaar is a distributed revision control system. Launchpad provides hosting services for bzr, integrated with the bugtracker and mailing lists that we already use. Bazaar is available packaged for all major distributions. (sudo apt-get install bzr for Debian/Ubuntu and derivatives). Our repository can be http-browsed.

Switching from SVN

  1. Bazaar has interface very similar to SVN. For most (basic) cases, replacing svn with bzr in your commands will do what you expect (read Centralized usage and Local operations to see).
  2. Install bzr: sudo apt-get install bzr. Required version >= 1.16 (our choice for performance reasons: yade's launchpad branch is in format not readable by pre-1.16 clients). Get latest version here if your distribution doesn't have 1.16 yet.
  3. Introduce yourself to Launchpad before committing the repository
  4. If you have some uncommited changes in the SVN checkout on your disk, they are not lost (unless you added/deleted/renamed files). In that case, you should
    1. Save the diff from the svn tree: cd trunk-svn; svn diff > /tmp/svn.diff
    2. Checkout from the bzr repository (see below)
    3. Apply the diff to the bzr repository: cd trunk-bzr; patch -p0 < /tmp/svn.diff
    4. Commit within bzr: bzr commit -m "Some commit message"

Centralized (SVN-like) usage

All developers work on the same branch (or branches). They run update to get their checkout up-to-date, then commit to publish their changes to the central location. This is familiar to SVN users.

Getting latest revision from Launchpad (lp)

(NB for ex-svn-users : no difference between committable and non-committable)

bzr checkout lp:yade

This will download the last revision in a sub-folder "yade". If you have weak internet-connection, you can use --lightweight key to escape downloading all historical revision data. It will work much more faster:

bzr checkout lp:yade --lightweight

Once you have done this for the first time, you'll download the last changes made by others, if you go into this folder "yade", and type :

bzr update (bzr up works)

Comparing your revision with latest revision from lp

Before daring to update with "bzr up", you can compare your local revision with the one that has just been commited. Type :

bzr st -r branch:lp:yade

for few informations (the names of modified/added/... files). Or :

bzr diff -r branch:lp:yade

for expanded informations (the precise differences)

Comparing your revision with a former revision from lp

If, for any reason, you want to compare your local revision with a former revision of yade (rev X, commited long time ago), type :

bzr st/diff -r branch:lp:yade -r X


(You need to set your keys and login for this as described here. You also must be member of the yade-dev team, if you commit to the main branch)

bzr commit -m 'You have to add here the description of your changes'

Local commit

This command has no SVN equivalent. It commits changes to your disk, without uploading them. That can be useful if you work offline or are not sure if your changes wouldn't interfere with other's work before you have thoroughly tested them. (Your changes will be commited upstream as soon as you do commit without the --local option. )

bzr commit -m 'You have to add here the description of your changes' --local

Local operations

Show only names of changed files

bzr status                   # "bzr st" works also

Show more expanded diff information

bzr diff

Add/delete/move files

bzr add path/to/your/file
bzr rm path/file
bzr mv path/old path/new

Renaming files

If you want change the name of some classes, the best is to use one existant python script (which uses some bzr instructions). Type, from your source folder :

 scripts/rename-class.py OldName NewName

Revert to a particular revision

If you need to roll back the trunk to a particular revision, use:

bzr revert -r 1111

where 1111 - the number of desired revision. Be carefull, unlike "bzr update", the command "bzr revert" will erase your local changes.

Introducing yourself to Launchpad

If you want to commit to it (for which you need the sftp access), register at Launchpad and upload your public key, which will authenticate you (Launchpad doesn't use password authentication for sftp). Then you need to become member of yade-team, which is the repository owner; team administrators are eudoxos and cosurgi and they will grant you membership when you apply for it via launchpad.

Creating your SSH key

Do this only if you don't have ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub files.

  1. Install OpenSSH. On Ubuntu, you can install OpenSSH by opening your terminal and typing: sudo apt-get install openssh-client
  2. Once OpenSSH is installed, stay in the terminal and type: ssh-keygen -t rsa
  3. When prompted, press Enter to accept the default file name for your key.
  4. Enter and then confirm a password to protect your SSH key (you may leave the password blank; in that case, no password will be asked when you work with launchpad).

Your key pair is stored in ~/.ssh/ as id_rsa.pub (public key) and id_rsa (private key) now.

Registering the key with Launchpad

Your public key must be uploaded to Launchpad.

  1. Open your public key ~/.ssh/id_rsa.pub in a text editor and copy its contents to your clipboard.
  2. Go to https://launchpad.net/~your-id/+editsshkeys your SSH keys page
  3. Paste your public key into the text box and then click the Import public key button to continue.

Tell bzr what launchpad login you have

bzr launchpad-login your-id

If the operation is successful, Bazaar will give you no message.

De-centralized usage

In this case (no equivalent in SVN), each developer has their own branch or branches, plus commit rights to the main branch. They do their work in their personal branch, then merge it into the mainline when it is ready. This allows:

  • Easier organization of work - separate changes can be developed in their own branches
  • Merging one another's personal branches when working on something together.

Getting latest revision from Bazaar on Launchpad

bzr branch lp:yade

Commit to the local branch

bzr commit -m 'You have to add here the description of your changes'

Pushing local commits upstream

bzr push lp:yade

Previous commits to the local branch will be pushed to launchpad repository.

Other stuff

Conflicts handling

If you get "Contents conflict in FILE", Bazaar will emit THIS, OTHER and BASE files. (They may be regular files, symlinks or directories). But it will not include a "main copy" of the file with herringbone conflict markers. It will appear that the "main copy" has been renamed to THIS or OTHER.

To resolve this, use "bzr mv" to rename the file back to its normal name, and combine the changes manually. When you are satisfied, run:

bzr resolve FILE

or for all conflicts:

bzr resolve

Learn more

bzr help
bzr help commands