Darcs plugin for Trac
root
========================
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.