========================
 Darcs backend for Trac
========================

This package implements a darcs backend for Trac supporting the new
`multirepository feature`__, that has been merged in the current
`Trac 0.12`__.

__ http://trac.edgewall.org/wiki/MultipleRepositorySupport
__ http://trac.edgewall.org/milestone/0.12

It used to work on 0.11, and even with 0.10, at least up to version
0.8 of the backend... No time to even try, so no guarantee, sorry!

To use the module you can either install it or make an egg and copy
it in the right place.

Installation
============

You can install the module the usual way::

  $ python setup.py install [--prefix /usr/local]

Otherwise you can make an egg::

  $ python setup.py bdist_egg

and either install it globally with::

  $ easy_install dist/TracDarcs-someversion.egg

or manually copy the egg from the "dist" subdir into the environment's
"plugins" subdirectory

In general, follow the directions in TracPlugins.

Specific configuration options
------------------------------

Some feature can be altered by using the following trac+darcs specific
options in the ``[darcs]`` section of the configuration:

command : string
  This is the effective `darcs` executable that will be used. By
  default its ``darcs``, but you could set it to
  ``/usr/local/bin/darcs`` to use a newer version...

dont_escape_8bit : boolean
  False by default, maps to the `darcs` ``$DARCS_DONT_ESCAPE_8BIT``
  behaviour.

possible_encodings : string
  By default 'utf-8,iso8859-1', its a comma-separated-value list of
  possible string encodings to try one after the other, should a
  decode error occur while parsing darcs changesets.

max_concurrent_darcses : integer
  By default 0 to mean no limits, otherwise it is the maximum number
  of concurrent running darcs processes at the same time.

eager_annotations : boolean
  False by default, when true the content and the annotation cache of
  each modified file get computed immediately after a changeset gets
  added. This will move the heavy computation at pull time, rather
  than at first visit time. Of course, it will also enlarge the
  trac database...

Using a postcommit hook
-----------------------

The `recommended way`__ to trigger the sync between the repository and
the Trac instance is by using a darcs `post hook`__ on its ``apply``:
in this way the database will be updated as soon as darcs finish
applying any new changeset.

This can be accomplished by putting something like the following
setting into the repository ``_darcs/prefs/defaults`` file::

  apply posthook trac-admin TRAC_ENV changeset added $(pwd) $(python -m tracdarcs.changesparser)
  apply run-posthook

where of course you should replace `TRAC_ENV` with the full path of
the related trac instance.

.. note:: ``python -m tracdarcs.changesparser`` is just a quick way of
   extracting the list of changeset hashes from the the ``darcs
   changes --xml`` format: it accepts the input either as the
   ``$DARCS_PATCHES_XML`` or from standard input::

    $ darcs changes --xml | python -m tracdarcs.changesparser | head -3
    20100611081300-97f81-bc5c1f7acf0c168bbfa9fb911e3cc2a4e71d5eef
    20100610150339-97f81-cd1b73f2ba1b1d98c28542ecbd1d5e2bd9052056
    20100512164420-97f81-de3fbc73d7c401fb92503ef1b25e19e0f48d2ad1

At that point, you could deactivate the per request sync that Trac
still does by default, by setting ``repository_sync_per_request`` to
an empty value in the ``[trac]`` section of the configuration.

__ http://trac.edgewall.org/wiki/0.12/TracRepositoryAdmin#ExplicitSync
__ http://darcs.net/manual/node7.html#SECTION00712000000000000000