- Download and Installation
- Bugs and Limitations
- Implementation Notes
Mercurial Plugin for Trac (#1847)
Please take care to use a recent version of the plugin before reporting issues. See the version table below.
The mercurial plugin for Trac is now hosted in its own Mercurial repository, mercurial-plugin (it was about time!)
hg clone https://hg.edgewall.org/trac/mercurial-plugin
Detailed Change Logs:
- active / supported
- inactive / unsupported
Download and Installation
Releases and compatibility matrix
|Version||mercurial-plugin||Trac||Compatible with hg|
|18.104.22.168||mercurial-plugin@c91c42e (1.0 branch) .egg||branches/1.0-stable (1.0.x), trunk (1.1.x)||1.1.x to 3.2|
|22.214.171.124||mercurial-plugin@28d2535 (1.0 branch)||branches/1.0-stable (1.0.x), trunk (1.1.x)||1.1.x to 2.2.2, 2.3? tip?|
|0.13.0.5||plugins/0.13/mercurial-plugin@10900||trunk (0.13dev)||1.1.x to 2.0.2, tip?|
|0.13.0.4||plugins/0.13/mercurial-plugin@10880||trunk (0.13dev)||1.1.x to 1.7.5, tip?|
|0.13.0.3||plugins/0.13/mercurial-plugin@10620||trunk (0.13dev)||1.1.x to 1.7.5, tip?|
|0.13.0.2||plugins/0.13/mercurial-plugin@10527||trunk (0.13dev)||1.1.x to 1.7.5, tip?|
|0.12.0.29||mercurial-plugin@a97b17f1bac7 (0.12 branch)||branches/0.12-stable (0.12.x)||1.1.x to 2.0.2, tip?|
|0.12.0.28||plugins/0.12/mercurial-plugin@10878||branches/0.12-stable (0.12.x)||1.1.x to 1.7.5, tip?|
|0.12.0.27||plugins/0.12/mercurial-plugin@10619||branches/0.12-stable (0.12.x)||1.1.x to 1.7.5, tip?|
|0.12.0.26||plugins/0.12/mercurial-plugin@10524||branches/0.12-stable (0.12.x)||1.1.x to 1.7.5, tip?|
Consult the version table below to check which precise version you need for your version of Trac. If you want to get a specific revision, add an
svn up -rxxx step to the instructions below, after the checkout.
Installation of the plugin:
hg clone http://hg.edgewall.org/trac/mercurial-plugin#0.12
hg clone http://hg.edgewall.org/trac/mercurial-plugin#1.0
Then from the checkout (
cd mercurial-plugin), you have various installation options:
- create an "egg" which you can copy to your
$TRACENV/plugins, for example:
$ python setup.py bdist_egg
- install it in the current Python (or virtualenv) installation:
$ python setup.py install
- similar to the above, but directly use the code from the checkout (ideal for hacking):
$ python setup.py develop
You can download Mercurial itself from Hg:Download.
We try to maintain backward compatibility with versions of Mercurial as old as 1.1, up to the latest. Better use a recent version however.
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).
Note! Mercurial's library.zip contains pyd-files, which normal python import can't use (py2exe uses a special importer that allows that), but if you unzip library.zip somewhere and add that directory, it will work on Windows (tested with tracd).
Alternatively you can install the pre-built Mercurial Python modules from http://bitbucket.org/tortoisehg/thg-winbuild/downloads/
You may also want to experiment with the newly introduced Mercurial:HackableMercurial distribution.
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 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.
Since the version 0.11 of the 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.
When creating a new environment with TracAdmin
- for the repository type, specify
hginstead 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 (defaults to yes) show_rev = yes # -- Changeset hash format node_format = short # hex: Show the full SHA1 hash # short: Show a shortened hash for the changesets (default)
Setting up post-commit hooks
For 0.12 and later:
If you want to enable post-commit hook functionality on your repository, add the following to your repository's
.hg/hgrc file (since ):
[hooks] ; If mercurial-plugin is installed globally commit = python:tracext.hg.hooks.add_changesets changegroup = python:tracext.hg.hooks.add_changesets ; If mercurial-plugin is installed in a Trac plugins directory commit = python:/path/to/hooks.py:add_changesets changegroup = python:/path/to/hooks.py:add_changesets [trac] env = /path/to/env trac-admin = /path/to/trac-admin
Remember to change
/path/to/trac-admin to reflect your environment. If TracMercurial is installed in a Trac
plugins directory, you will also have to download hooks.py and place it somewhere accessible.
You must also enable the CommitTicketUpdater functionality in your
trac.ini by adding
tracopt.ticket.commit_updater.* = enabled
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, with a very loose definition of next, see #8417).
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
Plain changeset numbers are also recognized, provided they are long enough (12 to 40).
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:
Since r6443, the MQ extension is supported. If you happen to have applied mq patches in your repository, Trac will show the corresponding patch names as Tags: in the changeset view.
Also, with the 0.12 branch of the plugin (and the MultipleRepositorySupport branch of Trac), you can browse jointly the main repository and the repository for the associated Mercurial queue, if any (i.e. if you versioned your patch queue using
hg qinit -c and
hg qcommit). Furthermore, if you declare such a mercurial repository to be a MQ repository, then all the patches will be correctly rendered as patches, regardless of the patch name (see r6462 for details).
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.
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.
HG Forest Support Subrepositories 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.
Note that with the MultipleRepositorySupport branch of Trac, it should be possible to implement an IRepositoryProvider component knowing about the
forestextension and adding besides the repository for the forest itself, the managed repositories as well.
Add your cool feature here…
- Mercurial bundle attachments should be viewable in readable representation.
- Support for subrepositories mercurial extension
- Mercurial plugin support for pulling repository description from hgrc
- Way to configure by default displayed branch
- Enhancing TracMercurial plugin to use new server-command protocol
- Mercurial bookmarks as properties in browser
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
- No path history mode (i.e. show all create/delete operations that affected a given path)
To cache or not to cache?
However, producing diffs or even gathering the timeline events for repositories of such size is still too slow. For the diffs, we could reduce the amount diffs generated (see #2591, #7975). For the timeline, we should really have a cache, not only for the performance issue but also because the current heuristic for retrieving the changesets in a given period of time doesn't always work (see r5365).
"unsupported version control system hg"
If you get this message try the following two basic checks first:
- From a Python console session try to import the Mercurial module, if all goes well it should not complain:
You can also look at the
>>> from mercurial import ui, hg >>> repo = hg.repository(ui.ui(), '/path/to/a/mercurial/repo') >>> len(repo) 234
hg.__file__attribute to verify you're loading the expected Mercurial library.
- Log in as an user with
TRAC_ADMINpermission, and look in the
General / Plugins. Do you see the entry for the TracMercurial plugin there? If yes, is the MercurialConnector component enabled?
- CachedRepository support in TracMercurial
- Post-commit hook gives strange answer
- LookupError, <file> not found in manifest
- TracMercurial hooks.py dies when using TortoiseHg
- Abort: cannot follow file not in parent revision: "tracext/hg/backend.py"
- [hg] encoding setting is not used for files in hg
Hacking on Mercurial:
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.
hg-plugin-changeset.png (58.7 KB) - added by 9 years ago.
Changeset view, showing multiple parents. Note that the diffs are providing against each parent.
hg-plugin-browser.png (69.2 KB) - added by 9 years ago.
Browser view, showing the pulldown menu of tags
hg-plugin-annotate.png (56.3 KB) - added by 7 years ago.
Screen shot of the annotate / blame feature of Trac 0.11, on the .hgtags file of the Mercurial repository
TracMercurial-126.96.36.199-py2.7.egg (43.1 KB) - added by 13 days ago.
.egg for the 188.8.131.52 release
Download all attachments as: .zip