==============================
gf.recipe.bzr buildout recipee
==============================

This recipe can be used to get development checkouts from Bazaar repositories
for zc.buildout.

**IMPORTANT COMPATIBILITY CHANGE: SEE BELOW**

Documentation
=============

Goals
-----

- Allow fetching eggs directly from bzr repositories.

- The specified repositories are branched locally on the first buildout run. It
  is possible to use these local branches for development and make local
  changes. The local changes can be committed locally, and can be pushed back
  to the remote repository or to any other location.

- When buildout is run again, the branches are updated (pulled) automatically
  from the remote location. If pulling causes conflicts, buildout continues
  gracefully, but it gives an error message to notify the user about the problem.
  The parent branch (pull) location remembered by bazaar will be
  used for pulling, so it is possible to change this any time from bzr, and
  the recipe will use the new location from that point on.

- Local changes can be pushed back manually to the remote branches. This is
  not enforced and is in the responsibility of the user. The recipe does not
  do any checks at uninstall time, neither does it remove the local branches.
  Please note however that your changes will not propagate upstream, unless
  you do the necessary push.

- Parameters are similar to those used with "infrae.subversion" and also
  compatible with the "bazaarrecipe" package.

- With bzr-svn, the remote branch can also be an svn branch. So it actually can
  be used to branch off native svn repository branches as well (although,
  performance of updates will depend on bzr-svn's performance,
  thus infrae.subversion may provide faster operation for svn.)


Compatibility changes
---------------------

The default recipe is now doing a relaxed repository checkup, compared
to the recent versions. This is described in the goals. Important
changes from recent versions:

- On update, if "pull" is unsuccesful, the recipe will give an error with the
  bzr command output, but it will not cause buildout to stop with an error.
  The developer needs to look at this output to realize that the update has
  not taken place.

- There is no uninstall any more. The developer is no more enforced to commit
  and push her changes. Note that the branch will never be removed, thus
  the developer won't loose local changes in any way, unless she willingly
  deletes the branch.

**The old behaviour is still available, in the "strict" recipe**::

    [bzr]
    recipe = gf.recipe.bzr:strict
    ...

If you find problems using the recipe after an upgrade, please try to use
the "strict" recipe.


Usage
-----

Usage example::

    [bzr]
    recipe = gf.recipe.bzr
    urls =
        http://bazaar.launchpad.net/~kissbooth/kss.plugin.sdnd/trunk kss.plugin.sdnd
        http://bazaar.launchpad.net/~kissbooth/kss.plugin.livesearch/trunk kss.plugin.livesearch
    in_parts = False
    http_authentication = username:password

This will ``bzr get`` the branches to ``bzr/kss.plugin.sdnd`` and
``bzr/kss.plugin.livesearch``.  Branches are pulled if buildout is called.

No directories are really removed on uninstall, this has the consequence that
if the buildout configuration is changed, the local repositories will not
follow the new pull location, but instead will continue using the pull location
known by bzr.

The ``in_parts`` option
"""""""""""""""""""""""

``in_parts`` is by default false, which means the directory that holds the branches
is created in the buildout root. This is the default mode as it is handy for
development. If ``in_parts = True`` is specified, then the directory will be
created in the parts directory (compatible with infrae.subversion).

The ``http_authentication`` option
""""""""""""""""""""""""""""""""""

If ``http authentication`` is specified as ``username:password``, it will be used for
authenticating into http and https realms. This is rarely needed as ssh offers
a more comfortable repository access, but it allows password protected http
access that would not be easy (or possible at all) otherwise.

The option is inactive with ``bzr+ssh://`` repository urls.

The ``develop`` option
""""""""""""""""""""""

The branches fetched by the recipe are also installed as development eggs, by
default. The ``develop = False`` option can be used to force the recipe not to
develop the eggs. This can be useful, for example, to use buildout to update
local read-only bazaar mirrors of an svn repository::

    [kukit.js]
    recipe = gf.recipe.bzr
    urls=
        https://codespeak.net/svn/kukit/kukit.js/trunk              trunk
        https://codespeak.net/svn/kukit/kukit.js/branch/1.2         1.2
        https://codespeak.net/svn/kukit/kukit.js/branch/1.4         1.4
    develop = False

    [kss.demo]
    recipe = gf.recipe.bzr
    urls=
        https://codespeak.net/svn/kukit/kss.demo/trunk              trunk
        https://codespeak.net/svn/kukit/kss.demo/branch/1.2         1.2
        https://codespeak.net/svn/kukit/kss.demo/branch/1.4         1.4
    develop = False


Other configuration needed
--------------------------

In addition you also need to include the eggs you configured with the recipe,
in the buildout section::

    [buildout]
    ...
    eggs =
        ...
        kss.plugin.sdnd
        kss.plugin.livesearch


