HOWTO use bzr with OCamlForge

Table of contents

Bazaar
Developer access
Setting up your repository
FAQ

Bazaar

Bazaar (also known as bzr) is an easy to use, distributed, version control system with an emphasis on correctness and robustness that allows a great variety of workflows.

Before going any further, we recommend you read the five minute tutorial. The explanations below are just meant to help you to find your marks. It emphasizes the points specific to OCamlForge. Please refer to the official documentation for more details.

Developer access to an existing repository

A recommended workflow is to keep a copy of the upstream branch and develop in "feature/bugfix branches". To improve space efficiency, let us start by creating a shared repository (if you do not want to do this, you can skip to the next point):
```
bzr init-repo unix-name
```
where unix-name is be the directory that will hold your branches. You can name it whatever you like but to ease remembering its content I usually use the unix-name or the module-name of the project.
Go to the directory you just created
```
cd unix-name
```
and get a copy of the main development branch:
```
bzr branch sftp://bzr.ocamlcore.org//bzrroot/unix-name/module-name/trunk/
```
This will create a directory trunk with the branch. (The module name and its main branch name — frequently called trunk as above — should be given to you by the other developers of the project. If it is not the case, log in to bzr.ocamlcore.org and do ls -R /bzrroot/unix-name.) You can update that copy with bzr pull (being in the directory trunk).
Develop your features in separate branches. To make a branch, say feature-XXX, do:
```
bzr branch trunk feature-XXX
```
Finally, make your changes public by pushing them to the main branch
```
bzr push sftp://bzr.ocamlcore.org//bzrroot/unix-name/module-name/trunk/
```
or to a (new) branch
```
bzr push sftp://bzr.ocamlcore.org//bzrroot/unix-name/module-name/feature-XXX/
```
(the push must only be specified the first time, afterwards you can just write bzr push and bzr will use the remembered URL).

Setting up your repository on OCamlForge

Ask the OCamlForge team to create the root of your repository /bzrroot/unix-name where you will store all your modules and branches — this is their only duty, the rest is yours! Make sure that you have a ssh key set up in your ocamlforge account and that you can access the shell (ssh bzr.ocamlcore.org).
In order for your repositories to be writable by all members of your team, they need to be created with group write premission. To do that, upload a .bashrc file with
```
scp .bashrc shell.forge.ocamlcore.org:
```
where .bashrc must contain (at least):
```
umask 0002
```
We suggest that you start by creating a shared repository for disk space efficiency (that will enable history to be shared between your branches):
```
bzr init-repo --no-trees sftp://bzr.ocamlcore.org//bzrroot/unix-name/module-name
```
Then, to push a branch that you have on your disk — let us call it trunk —, cd into it and issue
```
bzr push sftp://bzr.ocamlcore.org//bzrroot/unix-name/module-name/trunk/
```
(this is for the first time only, bzr will remember the location so you will only have to write bzr push).

FAQ

Login name

If your ocamlcore login name — let us call it logcore — is different from your local machine login, you have two possibilities. First, you can specify it in the URL:

sftp://logcore@bzr.ocamlcore.org//bzrroot/...

Second, if you use openssh, create a file ~/.ssh/config containing

Host *.ocamlcore.org
  User logcore
  Compression yes

bzr ≤ 1.5

If you use bzr ≤ 1.5 (and do not want to upgrade), you must take care of a couple of additional things due to a sftp bug deleting the sgid bit (a workaround has been commited in bzr 1.6). First, when you create your repository, choose a packed format with --pack-0.92 or --rich-root-pack. With --rich-root-pack, you have the added bonus that you will also be able to use the bzr-svn plugin to store your history under SVN. Second, after the first push of a branch, you must enable the sgid bit on your directories. To do that,

ssh
    bzr.ocamlcore.org

and issue

cd /bzrroot/unix-name/module-name/
chgrp -R scm_unix-name .
find . -type d -exec chmod g+s {} \;

You do not need to do this after subsequent pushes of the same branch. (The reason for choosing a pack format here — in addition to their better efficiency — is that no new directories will be created after the initial push.)