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