= Mercurial Plugin for Trac (#1847) = There is an '''experimental''' plugin for Trac [milestone:0.9] which enables [http://www.selenic.com/mercurial Mercurial] to be used instead of [http://subversion.tigris.org Subversion] for the VersioningSystemBackend. ''The plugin being experimental, expect some rough edges and a somewhat instable set of features/documentation...'' == Download and Installation == ==== Trac ==== The plugin needs a slightly modified version of Trac 0.9, which offers support for pluggable SCM backends. This version can be found in source:sandbox/vc-refactoring Simply do: {{{ svn co http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring trac-for-hg }}} and install from there (`cd trac-for-hg; python setup.py install`). The plugin itself is available from source:sandbox/mercurial-plugin Check it out, too: {{{ svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin mercurial-plugin }}} and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`). Note that you'll need [http://peak.telecommunity.com/DevCenter/setuptools setuptools] >= 0.6 for that (I used setuptools-0.6a5). ===== Releases ===== || '''Version''' || mercurial-plugin || Trac vc-refactoring || || 0.1 || r2491 || r2491 || ==== Mercurial ==== The plugin has been tested with Mercurial 0.7 and a few later versions (upto Changeset 1481:acd1832ebf31 from http://selenic.com/hg). It won't work with earlier versions. You can download hg from [http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download]. == Configuration == For general instructions about plugins, see also TracPlugins. The plugin egg can be added to the `plugins` folder of an existing environment, or to a brand new environment. Note that if you create a new environment, it's currently necessary to leave the repository directory '''empty''' during the `initenv` step (''this will probably be fixed soon''). Then, you need to specify which version control backend has to be used: {{{ [trac] repository_type = hg repository_dir = /path/to/my/hg/repository }}} ''Note: those installing from 0.9 + the patch on #1847 still have to specify `repository_dir=hg:/path/to/my/hg/repository`'' Also, you'll need to explicitely disable the SVN components: {{{ [components] trac.versioncontrol.svn_fs.* = disabled }}} ''Note: that constraint will most certainly be lifted in the future'' Finally, if you installed the egg by doing a `python setup.py install`, there's the additional constraint of specifically ''enabling'' the plugin: {{{ [components] trac.versioncontrol.svn_fs.* = disabled hgtrac.* = enabled }}} == Features == The Mercurial support is pretty basic, but works well. I've tested that on the Mercurial repository itself and the performance is quite good, even if there's currently ''no'' caching in the database (I'm still not decided if that's a feature or a bug). For those used to Subversion in general and Subversion repository browsing in Trac in particular, there are a few differences worth noting. === Mercurial Changesets === ==== Changeset Navigation ==== In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is ''not'' purely sequential, as it is in Subversion. Instead of a ''flat'' history of successive changesets, we actually navigate a DAG of changesets. This means a changeset can have multiple parents (0, 1 or 2) and multiple children as well (0 to n). Therefore, ''Previous Changeset'' is a link to the first parent, and ''Next Changeset'' is a link to the first children. In case there are additional parents or children, these are shown as additional changeset properties (''Parents'' or ''Children''), placed below the ''Author'' property and above the ''Message'' property. [[Image(hg-plugin-changeset.png)]] Another additional changeset property is the list of ''Tags'' that might be associated with a changeset. ==== Wiki syntax ==== The Wiki syntax has been extended a bit, to cope with the hexadecimal notation of hg changesets. E.g `[8ef2]` would link to the changeset 8ef2ba892518c115170398ec754bd1c27cab271f ... Also, it is possible to refer to changesets using the changeset: prefix (or cset: or chgset:, for hgweb compatibility). The tag: prefix can be used to refer to symbolic tags, although this is not a requirement (using. e.g. `cset:tip` would work too). Finally, the branch: prefix has a special meaning, as this will not select the specified revision, but the head which is reachable from that revision. === TracBrowser changes === The TracBrowser ''View revision'' form has been extended with pulldown menus for jumping to a given tag or branch (in Mercurial, a branch within a repository corresponds to a head, i.e. a changeset without children): [[Image(hg-plugin-browser.png)]] == Bugs and Limitations == There are still a lot of things that can be improved. === Features that Trac+svn has but not currently implemented for Trac+hg === * History doesn't follow copy/move operations * No ''path history'' mode (i.e. show all create/delete operations that affected a given path) === Multi-repository support === First and foremost, even if Mercurial allows intra-repository branching, it strongly supports the use of branching by cloning the full repository. Therefore, it is common to have a lot of hg repositories around, each devoted to the implementation of some particular feature. Trac should support this by the way of multiple repository support within a single environment (see #2086). === Arbitrary diff support === The TracDiff features should be supported by TracMercurial too. === To cache or not to cache? === I happen to like to current database-free implementation of the Mercurial support. It makes it quite easy to change the `repository_dir` on the fly, and this flexibility is good. Also, hg being remarkably efficient, as everybody knows, the performance is quite good... Except in one case, getting the history of a directory. There, I suspect that the database cache would be quite useful. But I have yet to try on a big repository (e.g. the kernel) with either approach before concluding. In any case, thanks to the vc refactoring, the possibility will be offered to choose between a direct access or a cached access, as it's done for Subversion, svn: (cached) or direct-svn-fs: (direct access). ''cboos: I think I made up my mind, now that I tried to browse the kernel repo, it's way too slow without a db! Also, the way the diffs are produced currently (i.e. by Trac, from the full content of the files) is also too slow to be usable on such big repositories (e.g. the kernel changeset fc66195f585a took 7 minutes to be displayed on my machine). We need to get the diffs directly from hg.'' === Cool Features === ''Wild ideas'' section... ==== Visualize branches and merges ==== There should be a way to show graphically the branch and merge points within the revision log view. Not something as fancy as `hgk`, but nonetheless something that will make the changeset relationships immediately obvious. ==== Search over the source ==== A search provider could do the equivalent of an `hg grep`. ==== Highlight Conflict Resolution ==== While visualizing changeset diffs for merge changesets, we already show the changes relative to both parents, which helps to understand how conflicts (if any) were solved. But this can be improved by specifically highlighting lines that differs from both parents. ==== ''Add your cool feature here...'' ==== ---- == Implementation Notes == I'm interested in feedback concerning the code, in particular: * concerning Trac, there are only a few changes to the standard modules, !ChangesetModule (the additional properties) and !BrowserModule (the tags and branches support). Those changes could possibly be promoted to the generic level, therefore removing the need for having to explicitely disable the SVN components... * concerning Mercurial, I'm pretty sure I did things in a sub-optimal way, as I was discovering the guts of hg while writing the plugin. Therefore, I'll be pleased to get tips for improvements. '' -- ChristianBoos ''