|Version 41 (modified by 14 years ago) ( diff ),|
- Download and Installation
- Bugs and Limitations
- Implementation Notes
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 sandbox/mercurial-plugin works fine with Trac 0.10.3, though it will lack the "quickjump" to a branch or tag feature (this was implemented in source:sandbox/vc-refactoring, but is only available in the mainline for 0.11).
The plugin itself is available from source:sandbox/mercurial-plugin
Check it out:
svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin
and create an "egg" from there
$ cd mercurial-plugin $ python setup.py bdist_egg
One of the advantage of using this version is that you won't need to install ClearSilver anymore; instead you'll need the Genshi template engine (which is Python only, and therefore straightforward to install).
That version of the Mercurial plugin also supports of the new features added in 0.11 to the TracBrowser:
- quickjump to a tag or branch
- blame support
- custom property renderers (sandbox/property-renderers-tmp, not yet in trunk)
svn co http://svn.edgewall.com/repos/trac/trunk trac svn co http://svn.edgewall.org/repos/genshi/trunk genshi
and install from there:
$ cd trac $ python setup.py install $ cd .. $ cd genshi $ python setup.py install
(for Genshi, you might prefer to use a packaged release, see Genshi:GenshiDownload, or to easy_install it)
Then, you need the plugin itself:
svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.11
create an "egg" from there:
$ cd mercurial-plugin-0.11 $ python setup.py bdist_egg
Note that you'll need setuptools ≥ 0.6 for that (I used setuptools-0.6a9).
|Version||mercurial-plugin||Trac vc-refactoring||Compatible with hg|
|0.11.0.1||latest-0.11||0.11 or trunk||0.9, tip|
|0.10.0.2||0.10-stable||0.10||0.7, 0.8, 0.9, tip|
|0.2||r3014||trunk@2900||0.7, 0.8, tip|
|0.2||r2905||r2905||0.7, 0.8, tip|
|r2620||r2620||0.7, tip with 1d7d0c07|
|0.1||r2514||r2511||0.7, tip without 1d7d0c07|
Note: 0.9.4 (and probably quite a few intermediate changesets between 0.9.3 and 0.9.4) interferes badly with the TH:AccountManager plugin when using Python 2.3.5.
It's not unlikely that other setups can be affected by the problem, as basically any code that relies on trapping the
ImportError, after the
mercurial.demandimport mechanism has been activated, will fail.
The plugin has been tested with recent development versions of Mercurial (upto Changeset 3324:34f08b8883cf from http://selenic.com/hg) and also with Mercurial 0.7 and 0.8. It won't work with earlier versions, in particular not with 0.6x.
The plugin for 0.11 takes benefit of some new features introduced after the 0.8.2 release of Mercurial, and therefore needs at least a 0.9 version of Mercurial.
You can download Mercurial itself from Hg:Download.
On Windows, it looks like it's possible to re-use the Mercurial library coming from the installer,
see this mail
(though to my knowledge, it is not possible to achieve this using PYTHONPATH and PATH: it fails with
ImportError: No module named handlers due to library.zip coming in the sys.path before the standard library).
The configuration has to be done on the Trac side,
there's nothing to do on the Mercurial repository side,
except for the fact that the repository should be made
accessible as a local repository.
Thanks to the distributed nature of Mercurial, that's
always possible (if the repository is not already local,
hg clone it).
Setting up the mercurial plugin
The TracMercurial-0.2 plugin egg should be added to the
plugins folder of the
environment, or it can be globally installed (
python setup.py install
python setup.py develop).
For general instructions about plugins, see also TracPlugins.
If you installed the egg globally and you're modifying an existing Trac environment to use the Mercurial backend, then you have to explicitly enable the plugin in TracIni.
For the 0.10 plugin, this is done like that:
[components] tracvc.hg.* = enabled
For the 0.11 plugin, the package has been renamed to
[components] tracext.hg.* = enabled
Setting up a Trac environment
You can either reuse an existing Trac environment, or create a brand new one.
For general instructions, see TracInstall.
For the repository type, specify
hg instead of the default
For the repository directory, specify the location of the Mercurial repository
(without the ending
Your <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
There's also a few Mercurial specific settings in TracIni:
[hg] # -- Show revision number in addition to the changeset hash show_rev = yes # -- Changeset hash format node_format = short # hex: Show the full SHA1 hash # short: Show a shortened hash for the changesets
The Mercurial support is pretty basic, but works well. I've tested that on the Mercurial repository itself and the performance is acceptable, even if there's currently no caching in the database (this is what I'm going to work on next). Don't even think about using the plugin on a Linux-kernel-sized Mercurial repository, you'll probably burn your disk and/or CPUs ;)
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 child. 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.
TracBrowser changes in 0.11
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):
There's also support for visual blame annotations:
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)
- Revision log ranges [xxx:yyy]
View arbitrary diffsimplemented in r6053
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).
Note that the last comment on the above ticket suggests a good workaround for this problem.
To cache or not to cache?
When you try TracMercurial on the kernel repo, you quickly realize that 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). See #2591.
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.
There's an existing web implementation by Alexander Schremmer:
http://moin.pocoo.org:8080/ (select a repo and then 'branchview' button on the top to see it in action)
Also, there is RevtreePlugin.
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.
Trac should allow for creating new repositories or clones of existing repositories. Maybe repository deletion and renaming should be supported, too.
Some Manuals, FAQs and a Forum for this project
I am a novice with Aptana/Eclipse and Mercurial. I was hoping this plugin would give me some assistance over the command line interface, but I cannot even understand how to use it from this plug in. I have an existing mercurial repository. What do I do next to use it? A forum might be useful, as I think there is a big audience for a GUI for mercurial, now that firefox has gone to it.
HG Forest Support
Support for the Forest extension for Mercurial. Forest extension allows operations on trees with nested Mercurial repositories, called forests. Those to some degree correspond to multi-project CVS/Svn/… repositories.
Already got most of it working, expect that it's pretty much hacked in the Trac 0.10.3 version of the mercurial plugin. Since it needs a bit more flexibile templating (in regards with the lookup/url's) this is hacked around node.path at the moment. Some (small/large?) issues remain but most of it is working.
Add your cool feature here…
I'm interested in feedback concerning the code, in particular 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