|Version 14 (modified by 16 years ago) ( diff ),|
Mercurial Plugin for Trac (#1847)
The plugin being experimental, expect some rough edges and a somewhat unstable set of features/documentation…
Download and Installation
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.
It has been partially ported to trunk and retired since,
but for TracMercurial, you still need the original
vc-refactoring branch, at revision 2620.
svn co -r2620 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 -r2620 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
0.6 for that (I used setuptools-0.6a5).
|Version||mercurial-plugin||Trac vc-refactoring||Compatible with hg|
|0.1||r2514||r2511||0.7, tip without 1d7d0c07|
|r2620||r2620||0.7, tip with 1d7d0c07|
The plugin has been tested with recent development versions of Mercurial (upto Changeset 1568:1d7d0c07e8f3 from http://selenic.com/hg) and also Mercurial 0.7 (but this needs at least r2514 of the mercurial plugin). It won't work with earlier versions.
You can download hg from Hg:Download.
The configuration has to be done on the Trac side, there's nothing to do on the Mercurial repository side, except that it should be made available locally.
Setting up a Trac environment
You can either reuse an existing Trac environment, or create a brand new one.
For general instructions, see TracInstall.
initenv command has been slightly modified
in the vc-refactoring code base: in addition to the
repository directory, it's also needed to specify the
For the repository type, specify
hg instead of the default
For the repository directory, specify the location of the Mercurial repository.
In all case, you <trac_environment>/conf/trac.ini configuration file
should have a
[trac] section similar to the following:
[trac] repository_type = hg repository_dir = /path/to/my/hg/repository
Note: those installing from 0.9 + the patch on #1847 will still have to specify
Also, currently you still need to explicitely disable the SVN components:
[components] trac.versioncontrol.svn_fs.* = disabled
Note: that constraint will most certainly be lifted in the future
Setting up the mercurial plugin
The TracMercurial-0.1 plugin egg should be added to the
plugins folder of the
For general instructions about plugins, see also TracPlugins.
Finally, if you installed an unpacked egg by doing a
python setup.py install
(useful for development), there's the additional constraint of specifically
enabling the plugin:
[components] trac.versioncontrol.svn_fs.* = disabled hgtrac.* = enabled
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.
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.
Another additional changeset property is the list of Tags that might be associated with a changeset.
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
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.
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):
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)
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
To cache or not to cache?
I happen to like to current database-free implementation of the Mercurial
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.
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
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…
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.
) - added by 16 years ago.
Changeset view, showing multiple parents. Note that the diffs are providing against each parent.
) - added by 16 years ago.
Browser view, showing the pulldown menu of tags
) - added by 14 years ago.
Screen shot of the annotate / blame feature of Trac 0.11, on the .hgtags file of the Mercurial repository
) - added by 5 years ago.
Download all attachments as: .zip