Edgewall Software

Changes between Initial Version and Version 1 of TracMercurial


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

Initial documentation for the hg-plugin

Legend:

Unmodified
Added
Removed
Modified
  • TracMercurial

    v1 v1  
     1= Mercurial Plugin for Trac (#1847) =
     2
     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.
     7
     8
     9== Download and Installation ==
     10
     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:
     17{{{
     18svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/vc-refactoring trac-for-hg
     19}}}
     20and install from there (`cd trac-for-hg; python setup.py install`).
     21
     22
     23The plugin itself is available from
     24  source:branches/cboos-dev/versioncontrol/hg-plugin
     25Check it out, too:
     26{{{
     27svn co http://projects.edgewall.com/trac/branches/cboos-dev/versioncontrol/hg-plugin .
     28}}}
     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).
     33
     34The initial release of the plugin was made at r2472 and works
     35well with the vc-refactoring branch at that revision.
     36
     37
     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].
     44
     45
     46== Configuration ==
     47
     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'').
     52
     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:
     55{{{
     56[trac]
     57repository_dir = hg:/path/to/my/hg/repository
     58}}}
     59
     60Also, you'll need to explicitely disable the SVN components:
     61{{{
     62[components]
     63trac.versioncontrol.svn_fs.* = disabled
     64}}}
     65''Note: that constraint will most certainly be lifted in the future''
     66
     67
     68== Features ==
     69
     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).
     74
     75For those used to Subversion in general and Subversion repository browsing
     76in Trac in particular, there are a few differences worth noting.
     77
     78=== Mercurial Changesets ===
     79
     80==== Changeset Navigation ====
     81
     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).
     88
     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.
     94
     95[[Image(hg-plugin-changeset.png)]]
     96
     97Another additional changeset property is the list of ''Tags'' that
     98might be associated with a changeset.
     99
     100==== Wiki syntax ====
     101
     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.
     111
     112
     113=== TracBrowser changes ===
     114
     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)]]
     119
     120
     121== Bugs and Limitations ==
     122
     123There are still a lot of things that can be improved.
     124
     125=== Features that Trac+svn has but not currently implemented for Trac+hg ===
     126
     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)
     130
     131=== Multi-repository support ===
     132
     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.
     137
     138Trac should support this by the way of multiple repository support
     139within a single environment (see #2086).
     140
     141
     142=== Arbitrary diff support ===
     143
     144The TracDiff features should be supported by TracMercurial too.
     145
     146
     147=== To cache or not to cache? ===
     148
     149I happen to like to current database-free implementation of the Mercurial
     150support.
     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).
     160
     161
     162=== Cool Features ===
     163
     164''Wild ideas'' section...
     165
     166==== Visualize branches and merges ====
     167
     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.
     171
     172==== Search over the source ====
     173
     174A search provider could do the equivalent of an `hg grep`.
     175
     176==== Highlight Conflict Resolution ====
     177
     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.
     182
     183==== ''Add your cool feature here...'' ====
     184
     185----
     186
     187== Implementation Notes ==
     188
     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.
     198
     199'' -- ChristianBoos ''