[[PageOutline(2-3,Contents)]] = Mercurial Plugin for Trac [[Image(mercurial_logo.png, width=80px, align=right)]] This a plugin for Trac which enables [https://www.mercurial-scm.org Mercurial] to be used as the VersionControlSystem for Trac. It was originally developed under #1847. Please use a recent version of the plugin before reporting issues. See the [#Releases version table] below. The Mercurial plugin for Trac is now hosted in its own Mercurial repository, [repos:mercurial-plugin]: {{{#!sh hg clone https://hg.edgewall.org/trac/mercurial-plugin }}} Detailed Change Logs: * active / supported - log:mercurial-plugin@1.0 (new features) - log:mercurial-plugin@0.12 (only for critical bug fixes) * inactive / unsupported - // log:plugins/0.13/mercurial-plugin // - // log:plugins/0.12/mercurial-plugin // - log:plugins/0.11/mercurial-plugin, see [./@90#Trac0.11 Trac 0.11] and [./@89#Settingupthemercurialplugin setting up the plugin for 0.11] Mercurial itself is released under the [https://www.mercurial-scm.org/wiki/License GPLv2 license]. == Download and Installation === Releases and compatibility matrix #Releases {{{#!table class="listing" ||= '''Version''' =||= '''mercurial-plugin''' =||= '''Trac''' =||= '''Compatible with hg''' =|| |---------------------------------------------------------------------------- || **1.0.0.10** ||\ || [source:mercurial-plugin@3fedb001bed9] ([source:mercurial-plugin@1.0 1.0] branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:branches/1.2-stable] (1.2.x), [source:branches/1.4-stable] (1.4.x) || 1.1.x to 6.1.x || |---------------------------------------------------------------------------- || 1.0.0.9 ||\ || [source:mercurial-plugin@ea0d3998e2c7] ([source:mercurial-plugin@1.0 1.0] branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:branches/1.2-stable] (1.2.x), [source:branches/1.4-stable] (1.4.x) || 1.1.x to 5.5.x || |---------------------------------------------------------------------------- || 1.0.0.8 ||\ || [source:mercurial-plugin@0417bb5def2e] ([source:mercurial-plugin@1.0 1.0] branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:branches/1.2-stable] (1.2.x), [source:trunk] (1.3.x) || 1.1.x to 4.6.1 || |---------------------------------------------------------------------------- || 1.0.0.7 ||\ || [source:mercurial-plugin@d9139f9] (1.0 branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:branches/1.2-stable] (1.2.x), [source:trunk] (1.3.x) || 1.1.x to 3.9 || |---------------------------------------------------------------------------- || 1.0.0.6 ||\ || [source:mercurial-plugin@e0c98f9] (1.0 branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:trunk] (1.1.x) || 1.1.x to 3.2 || |---------------------------------------------------------------------------- || 1.0.0.5 ||\ || [source:mercurial-plugin@bee9c8c] (1.0 branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:trunk] (1.1.x) || 1.1.x to 3.2 || |---------------------------------------------------------------------------- || 1.0.0.4 ||\ || [source:mercurial-plugin@c91c42e] (1.0 branch) [attachment:TracMercurial-1.0.0.4-py2.7.egg .egg] ||\ || [source:branches/1.0-stable] (1.0.x), [source:trunk] (1.1.x) || 1.1.x to 3.2 || |---------------------------------------------------------------------------- || 1.0.0.1 || [source:mercurial-plugin@28d2535] (1.0 branch) ||\ || [source:branches/1.0-stable] (1.0.x), [source:trunk] (1.1.x) || 1.1.x to 2.2.2, 2.3? tip? || |---------------------------------------------------------------------------- |---------------------------------------------------------------------------- || 0.13.0.5 || [source:plugins/0.13/mercurial-plugin@10900] || [source:trunk] (0.13dev) || 1.1.x to 2.0.2, tip? || |---------------------------------------------------------------------------- || 0.13.0.4 || [source:plugins/0.13/mercurial-plugin@10880] || [source:trunk] (0.13dev) || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- || 0.13.0.3 || [source:plugins/0.13/mercurial-plugin@10620] || [source:trunk] (0.13dev) || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- || 0.13.0.2 || [source:plugins/0.13/mercurial-plugin@10527] || [source:trunk] (0.13dev) || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- |||||||| || |---------------------------------------------------------------------------- || '''0.12.0.29''' || [source:mercurial-plugin@a97b17f1bac7] ([source:mercurial-plugin@0.12 0.12] branch) || \ ||[source:branches/0.12-stable] (0.12.x) || \ || 1.1.x to 2.0.2, tip? || |---------------------------------------------------------------------------- || 0.12.0.28 || [source:plugins/0.12/mercurial-plugin@10878] || \ ||[source:branches/0.12-stable] (0.12.x) || \ || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- || 0.12.0.27 || [source:plugins/0.12/mercurial-plugin@10619] || \ ||[source:branches/0.12-stable] (0.12.x) || \ || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- || 0.12.0.26 || [source:plugins/0.12/mercurial-plugin@10524] || \ ||[source:branches/0.12-stable] (0.12.x) || \ || 1.1.x to 1.7.5, tip? || |---------------------------------------------------------------------------- }}} === Trac Consult the version table to check which 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. The latest stable version is available on [pypi:TracMercurial PyPI]. The simplest method of installation is: {{{#!sh $ pip install TracMercurial }}} You can also install from a checkout of the source: {{{#!sh hg clone https://hg.edgewall.org/trac/mercurial-plugin#0.12 }}} or: {{{#!sh hg clone https://hg.edgewall.org/trac/mercurial-plugin#1.0 }}} Then from the checkout (`cd mercurial-plugin`), you have the following installation options: - Create an "egg" which you can copy to your `$TRACENV/plugins`: {{{#!sh python setup.py bdist_egg }}} - Install it in the current Python (or [pypi:virtualenv virtualenv]) installation: {{{#!sh python setup.py install }}} - Similar to the above, but directly use the code from the checkout (ideal for hacking): {{{#!sh python setup.py develop }}} === Mercurial You can download Mercurial itself from [https://www.mercurial-scm.org/wiki/Download 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. ==== Windows On Windows, it looks like it is possible to re-use the Mercurial library coming from the [Mercurial:BinaryPackages installer], see [https://www.mercurial-scm.org/pipermail/mercurial/2007-July/013827.html this mail]. However, 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 https://bitbucket.org/tortoisehg/files/downloads/ or https://www.mercurial-scm.org/release/windows/ You may also want to experiment with Mercurial:HackableMercurial distribution. == Configuration 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, simply `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` or a `python setup.py develop`. For general instructions about plugins, see also TracPlugins. If you installed the egg globally and you are modifying an existing Trac environment to use the Mercurial backend, then you have to explicitly '''enable''' the plugin in TracIni. {{{#!ini [components] tracext.hg.* = enabled }}} === Setting up a Trac environment You can either reuse an existing Trac environment or create a new one. For general instructions, see TracInstall. When creating a new environment with TracAdmin `initenv` command: - for the ''repository type'', specify `hg` instead of the default `svn`. - for the ''repository directory'', specify the location of the Mercurial repository, without the ending `.hg`. Your [wiki:TracIni /conf/trac.ini] configuration file should have a `[trac]` section similar to the following: {{{#!ini [repositories] repository.type = hg repository.dir = /path/to/my/hg/repository }}} There are also a few Mercurial specific settings in TracIni: {{{#!ini [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 [milestone: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 [10728]): {{{#!ini [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/env` and `/path/to/trac-admin` to reflect your environment. If TracMercurial is installed in a Trac `plugins` directory, you will also have to download [source:plugins/0.13/mercurial-plugin/tracext/hg/hooks.py hooks.py] and place it somewhere accessible. You must also enable the CommitTicketUpdater functionality in your `trac.ini`: {{{#!ini [components] tracopt.ticket.commit_updater.* = enabled }}} == Features Mercurial support is basic, but works well and has been tested on the Mercurial repository itself. The performance is acceptable, even if there is currently no caching in the database, see #8417. 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 [wikipedia:Directed_acyclic_graph 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. [[Image(hg-plugin-changeset.png, width=666px, border=2)]] Another additional changeset property is the list of ''Tags'' that might be associated with a changeset. ==== Wiki syntax The wiki syntax has been extended in this plugin to handle hexadecimal notation of hg changesets. For example, `[8ef2]` would link to the changeset 8ef2ba892518c115170398ec754bd1c27cab271f. Other extensions include: * Plain changeset numbers are also recognized, provided they are long enough (12 to 40). * 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, because using `cset:tip` would work too. * 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 The TracBrowser ''View revision'' form has pulldown menus for jumping to a given tag or branch. In Mercurial, a branch within a repository corresponds to a head, ie a changeset without children: [[Image(hg-plugin-browser.png, width=666px, border=2)]] There is also support for visual ''blame'' annotations: [[Image(hg-plugin-annotate.png, width=666px, border=2)]] === Mercurial Queue Since r6443, the MQ extension is supported. If you 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, ie 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). ==== 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. Starting with Trac [milestone:1.0], we show a graphical overview of the branch graph when viewing the log of the repository root (#1492). Also, there is the [th:RevtreePlugin]. ==== 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 differ from both parents. ==== Repository Management Trac should allow for creating new repositories or clones of existing repositories. Maybe repository deletion and renaming should be supported, too. ==== Subrepositories support //The forest extension has been superseded by support for [Mercurial:Subrepository nested repositories]. Replace //forest// below by //subrepository//.// (#9704) 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 most of it is working, expect that it's hackish in the Trac 0.10.3 version of the plugin. Since it needs a bit more flexible 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 `forest` extension and adding besides the repository for the forest itself, the managed repositories as well. ==== Add your requested feature here [[TicketQuery(component=plugin/mercurial,milestone=plugin - mercurial,status=!closed,type=enhancement)]] == Bugs and Limitations === Features in Trac+svn but not in Trac+hg * No ''path history'' mode, ie show all create/delete operations that affected a given path. === To cache or not to cache? Recent versions of the plugin (r7744 for 0.11 or r7757 for 0.12) have a greatly improved browsing speed. It's now possible to navigate on repositories of the size of the Linux kernel repo. 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). === Troubleshooting ==== "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: {{{#!pycon >>> from mercurial import ui, hg >>> repo = hg.repository(ui.ui(), '/path/to/mercurial/repo') >>> len(repo) 234 }}} You can also look at the `hg.__file__` attribute to verify you are loading the expected Mercurial library. * Log in as an user with `TRAC_ADMIN` permission, and look in the `Admin` pages, `General / Plugins`. Do you see the entry for the !TracMercurial plugin there? If yes, is the !MercurialConnector component enabled? ==== "Fatal Python error: PyImport_GetModuleDict: no module dictionary!" You might get hard crashes on Windows showing up such messages on the console, when running TracStandalone with the autoreload feature (`-r` / `--auto-reload`), in combination with recent Mercurial versions (> 3.7-rc). This is already fixed in the code, so either upgrade the plugin or apply the [changeset:4ccbdac1153a/mercurial-plugin corresponding fix]. === Known Issues [[TicketQuery(component=plugin/mercurial,milestone=plugin - mercurial,status=!closed,type=defect)]] == Implementation Notes Hacking on Mercurial: - [mercurial:MercurialApi] - [mercurial:ApiChanges] - [mercurial:CommandServer] and [mercurial:PythonHglib] (not yet used - see #10411) 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. -- ChristianBoos