Edgewall Software

Changes between Initial Version and Version 1 of TracMercurial

Nov 2, 2005, 7:05:57 PM (16 years ago)
Christian Boos

Initial documentation for the hg-plugin


  • TracMercurial

    v1 v1  
     1= Mercurial Plugin for Trac (#1847) =
     3There is an experimental plugin for Trac [milestone:0.9] which enables
     4[http://www.selenic.com/mercurial Mercurial] to be used
     5instead of [http://subversion.tigris.org Subversion]
     6for the VersioningSystemBackend.
     9== Download and Installation ==
     11==== Trac ====
     12The plugin needs a slightly modified version of Trac 0.9,
     13which offers support for pluggable SCM backends.
     14This version can be found in
     15  source:branches/cboos-dev/versioncontrol/vc-refactoring
     16Simply do:
     18svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/vc-refactoring trac-for-hg
     20and install from there (`cd trac-for-hg; python setup.py install`).
     23The plugin itself is available from
     24  source:branches/cboos-dev/versioncontrol/hg-plugin
     25Check it out, too:
     27svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/hg-plugin .
     29and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`).
     30Note that you'll need
     31[http://peak.telecommunity.com/DevCenter/setuptools setuptools]
     32>= 0.6 for that (I used setuptools-0.6a5).
     34The initial release of the plugin was made at r2472 and works
     35well with the vc-refactoring branch at that revision.
     38==== Mercurial ====
     39The plugin has been tested with Mercurial 0.7 and a few later versions
     40(upto Changeset 1481:acd1832ebf31 from http://selenic.com/hg).
     41It won't work with earlier versions.
     42You can download hg from
     43[http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
     46== Configuration ==
     48The plugin egg can be added to the `plugins` folder of an existing environment,
     49or to a brand new environment. Note that if you create a new environment, it's
     50currently necessary to ''not'' specify the repository directory during the
     51`initenv` step (''this will probably be fixed soon'').
     53In either case, you'll need to specify the backend scheme to be used
     54(here `hg:`) in front of the actual repository location, in TracIni:
     57repository_dir = hg:/path/to/my/hg/repository
     60Also, you'll need to explicitely disable the SVN components:
     63trac.versioncontrol.svn_fs.* = disabled
     65''Note: that constraint will most certainly be lifted in the future''
     68== Features ==
     70The Mercurial support is pretty basic, but works well. I've tested that
     71on the Mercurial repository itself and the performance is quite good,
     72even if there's currently ''no'' caching in the database
     73(I'm still not decided if that's a feature or a bug).
     75For those used to Subversion in general and Subversion repository browsing
     76in Trac in particular, there are a few differences worth noting.
     78=== Mercurial Changesets ===
     80==== Changeset Navigation ====
     82In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is
     83''not'' purely sequential, as it is in Subversion.
     84Instead of a ''flat'' history of successive changesets, we actually navigate
     85a DAG of changesets.
     86This means a changeset can have multiple parents (0, 1 or 2) and multiple
     87children as well (0 to n).
     89Therefore, ''Previous Changeset'' is a link to the first parent,
     90and ''Next Changeset'' is a link to the first children.
     91In case there are additional parents or children, these are shown as
     92additional changeset properties (''Parents'' or ''Children''),
     93placed below the ''Author'' property and above the ''Message'' property.
     97Another additional changeset property is the list of ''Tags'' that
     98might be associated with a changeset.
     100==== Wiki syntax ====
     102The Wiki syntax has been extended a bit, to cope with the hexadecimal
     103notation of hg changesets. E.g `[8ef2]` would link to the changeset
     1048ef2ba892518c115170398ec754bd1c27cab271f ...
     105Also, it is possible to refer to changesets using the changeset: prefix
     106(or cset: or chgset:, for hgweb compatibility).
     107The tag: prefix can be used to refer to symbolic tags, although this is not
     108a requirement (using. e.g. `cset:tip` would work too).
     109Finally, the branch: prefix has a special meaning, as this will not select
     110the specified revision, but the head which is reachable from that revision.
     113=== TracBrowser changes ===
     115The TracBrowser ''View revision'' form has been extended with
     116pulldown menus for jumping to a given tag or branch (in Mercurial,
     117a branch within a repository corresponds to a head, i.e. a
     118changeset without children): [[Image(hg-plugin-browser.png)]]
     121== Bugs and Limitations ==
     123There are still a lot of things that can be improved.
     125=== Features that Trac+svn has but not currently implemented for Trac+hg ===
     127 * History doesn't follow copy/move operations
     128 * No ''path history'' mode (i.e. show all create/delete operations that
     129   affected a given path)
     131=== Multi-repository support ===
     133First and foremost, even if Mercurial allows intra-repository branching,
     134it strongly supports the use of branching by cloning the full repository.
     135Therefore, it is common to have a lot of hg repositories around, each
     136devoted to the implementation of some particular feature.
     138Trac should support this by the way of multiple repository support
     139within a single environment (see #2086).
     142=== Arbitrary diff support ===
     144The TracDiff features should be supported by TracMercurial too.
     147=== To cache or not to cache? ===
     149I happen to like to current database-free implementation of the Mercurial
     151It makes it quite easy to change the `repository_dir` on the fly, and this
     152flexibility is good. Also, hg being remarkably efficient, as everybody knows,
     153the performance is quite good... Except in one case, getting the history
     154of a directory. There, I suspect that the database cache would be quite useful.
     155But I have yet to try on a big repository (e.g. the kernel) with either
     156approach before concluding. In any case, thanks to the vc refactoring,
     157the possibility will be offered to choose between a direct access or a
     158cached access, as it's done for Subversion, svn: (cached) or
     159direct-svn-fs: (direct access).
     162=== Cool Features ===
     164''Wild ideas'' section...
     166==== Visualize branches and merges ====
     168There should be a way to show graphically the branch and merge points within
     169the revision log view. Not something as fancy as `hgk`, but nonetheless
     170something that will make the changeset relationships immediately obvious.
     172==== Search over the source ====
     174A search provider could do the equivalent of an `hg grep`.
     176==== Highlight Conflict Resolution ====
     178While visualizing changeset diffs for merge changesets, we already
     179show the changes relative to both parents, which helps to understand
     180how conflicts (if any) were solved. But this can be improved by
     181specifically highlighting lines that differs from both parents.
     183==== ''Add your cool feature here...'' ====
     187== Implementation Notes ==
     189I'm interested in feedback concerning the code, in particular:
     190 * concerning Trac, there are only a few changes to the standard modules,
     191   !ChangesetModule (the additional properties) and !BrowserModule
     192   (the tags and branches support). Those changes could possibly be promoted
     193   to the generic level, therefore removing the need for having to explicitely
     194   disable the SVN components...
     195 * concerning Mercurial, I'm pretty sure I did things in a sub-optimal
     196   way, as I was discovering the guts of hg while writing the plugin.
     197   Therefore, I'll be pleased to get tips for improvements.
     199'' -- ChristianBoos ''