========================
 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. The latter requires adding that directory to
the ``PYTHONPATH`` if you wanna use the post hook as explained below.

Plugin activation
-----------------

In general, follow the directions in TracPlugins. At the minimum, the
plugin must be activated with something like the following in the Trac
instance's ``conf/trac.ini`` file::

  [components]
  tracdarcs.* = enabled

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 post apply 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
settings into the repository ``_darcs/prefs/defaults`` file::

  apply posthook trac-admin TRAC_ENV changeset added $(pwd) $(python -m tracdarcs.changesparser)
  apply run-posthook
  pull posthook trac-admin TRAC_ENV changeset added $(pwd) $(python -m tracdarcs.changesparser)
  pull 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`` environment variable (as set by darcs
   posthooks) 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

Related repositories
--------------------

When you manage multiple branches of the same darcs repository, you
may find useful to inform trac+darcs about that, so that it will show
additional properties on each changeset:

* a list of other "instances" of the same patch, that is when the
  changeset is present in other related repositories,

* a list of related repositories where the changeset is *not* present.

To do that, you simply group together the related repositories giving
them a common ``identity``, an arbitrary string.

You can see current identity of a repository with::

  $ trac-admin . repository identity master
  No identity set on repository master

and you can set it with::

  $ trac-admin . repository identity master ProjectFoo
  Identity of repository master set to ProjectFoo

You can adjust it with::

  $ trac-admin . repository identity master ProjectBar
  Identity of repository master set to ProjectBar (was ProjectFoo)

or remove it::

  $ trac-admin . repository identity master ""
  Identity removed from repository master

When browsing a changeset in a repository that shares its identity
with other repositories, you will see a property ``Present in``
listing the links to *instances* of the same patch in the other
related repositories, if there are any. At the same time, a property
``Missing in`` will show the complementary list, i.e. the related
repositories where the given patch is not present, if any.