Edgewall Software

Changes between Version 14 and Version 15 of TracMercurial


Ignore:
Timestamp:
Feb 14, 2006, 4:46:53 PM (16 years ago)
Author:
Christian Boos
Comment:

Update the documentation so that it matches the current implementation.

Legend:

Unmodified
Added
Removed
Modified
  • TracMercurial

    v14 v15  
    11= Mercurial Plugin for Trac (#1847) =
    22
    3 There is an '''experimental''' plugin for Trac [milestone:0.9] which enables
    4 [http://www.selenic.com/mercurial Mercurial] to be used
    5 instead of [http://subversion.tigris.org Subversion]
    6 for the VersioningSystemBackend.
     3There is an '''experimental''' plugin for Trac [milestone:0.10]
     4which enables [http://www.selenic.com/mercurial Mercurial]
     5to be used instead of [http://subversion.tigris.org Subversion]
     6as the VersioningSystemBackend for Trac.
    77
    88''The plugin being experimental, expect some rough edges
    99and a somewhat unstable set of features/documentation...''
    1010
     11Change Logs:
     12 * log:sandbox/mercurial-plugin
     13 * log:sandbox/vc-refactoring
    1114
    1215== Download and Installation ==
    1316
    1417==== Trac ====
    15 The plugin needs a slightly modified version of Trac 0.9,
    16 which offers support for pluggable SCM backends.
     18The plugin needs a slightly modified version of Trac 0.10.
    1719This version can be found in source:sandbox/vc-refactoring.
    18 It has been partially ported to trunk and retired since,
    19 but for TracMercurial, you still need the ''original''
    20 `vc-refactoring` branch, at revision 2620.
    2120
    2221Simply do:
    2322{{{
    24 svn co -r2620
    25 http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring trac-for-hg
    26 }}}
    27 and install from there (`cd trac-for-hg; python setup.py install`).
     23svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring
     24}}}
     25and install from there:
     26{{{
     27$ cd vc-refactoring
     28$ python setup.py egg_info
     29$ python setup.py install
     30}}}
    2831
    2932The plugin itself is available from source:sandbox/mercurial-plugin
     
    3134Check it out, too:
    3235{{{
    33 svn co -r2620 http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin mercurial-plugin
     36svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin
    3437}}}
    3538and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`).
    3639Note that you'll need
    3740[http://peak.telecommunity.com/DevCenter/setuptools setuptools]
    38 >= 0.6 for that (I used setuptools-0.6a5).
     41>= 0.6 for that (I used setuptools-0.6a9).
    3942
    4043===== Releases =====
    4144|| '''Version''' || mercurial-plugin || Trac vc-refactoring || Compatible with hg         ||
    4245||      0.1      ||       r2514      ||        r2511        ||  0.7, tip without 1d7d0c07 ||
    43 ||               ||    '''r2620'''   ||     '''r2620'''     ||  0.7, tip with 1d7d0c07    ||
     46||               ||       r2620      ||        r2620        ||  0.7, tip with 1d7d0c07    ||
     47||   '''0.2'''   ||    '''r2905'''   ||     '''r2905'''     ||  0.7, 0.8, tip  ||
    4448
    4549
    4650==== Mercurial ====
    4751The plugin has been tested with recent development versions of Mercurial
    48 (upto Changeset 1568:1d7d0c07e8f3 from http://selenic.com/hg)
    49 and also Mercurial 0.7 (but this needs at least r2514 of the mercurial plugin).
    50 ''It won't work with earlier versions.''
    51 
    52 You can download hg from
     52(upto Changeset 1704:c2755eba8631 from http://selenic.com/hg)
     53and also with Mercurial 0.7 and 0.8.
     54''It won't work with earlier versions, in particular not with 0.6x.''
     55
     56You can download Mercurial itself from
    5357[http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
    5458
     
    5862The configuration has to be done on the Trac side,
    5963there's nothing to do on the Mercurial repository side,
    60 except that it should be made available locally.
     64except for the fact that the repository should be made
     65accessible as a local repository.
     66Thanks to the distributed nature of Mercurial, that's
     67always possible (if the repository is not already local,
     68simply `hg clone` it).
     69
     70
     71=== Setting up the mercurial plugin ===
     72
     73The TracMercurial-0.2 plugin egg should be added to the `plugins` folder of the
     74environment, or it can be globally installed (`python setup.py install`
     75or a `python setup.py develop`).
     76
     77For general instructions about plugins, see also TracPlugins.
     78
     79If you installed the egg globally and you're modifying an
     80existing Trac environment to use the Mercurial backend,
     81then you have to explicitely ''enable'' the plugin in TracIni:
     82{{{
     83[components]
     84trac.versioncontrol.hg.* = enabled
     85}}}
     86Note that the above will be done automatically for a new installation,
     87during the `initenv` step.
     88
    6189
    6290=== Setting up a Trac environment ===
     
    6795For general instructions, see TracInstall.
    6896
    69 The TracAdmin `initenv` command has been slightly modified
    70 in the vc-refactoring code base: in addition to the
    71 ''repository directory'', it's also needed to specify the
    72 ''repository type''.
     97Since milestone:0.10, the TracAdmin `initenv` command has
     98now a ''repository type'' argument besides ''repository directory''.
    7399
    74100For the ''repository type'', specify `hg` instead of the default `svn`.
    75 For the ''repository directory'', specify the location of the Mercurial repository.
    76 
    77 In all case, you [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
     101For the ''repository directory'', specify the location of the Mercurial repository
     102(without the ending `.hg`).
     103
     104Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
    78105should have a `[trac]` section similar to the following:
    79106{{{
     
    83110}}}
    84111
    85 ''Note: those installing from 0.9 + the patch on #1847 will still have to specify `repository_dir=hg:/path/to/my/hg/repository`''
    86 
    87 Also, currently you still need to explicitely disable the SVN components:
    88 {{{
    89 [components]
    90 trac.versioncontrol.svn_fs.* = disabled
    91 }}}
    92 
    93 ''Note: that constraint will most certainly be lifted in the future''
    94 
    95 === Setting up the mercurial plugin ===
    96 
    97 The TracMercurial-0.1 plugin egg should be added to the `plugins` folder of the
    98 environment.
    99 
    100 For general instructions about plugins, see also TracPlugins.
    101 
    102 Finally, if you installed an unpacked egg by doing a `python setup.py install`
    103 (useful for development), there's the additional constraint of specifically
    104 ''enabling'' the plugin:
    105 {{{
    106 [components]
    107 trac.versioncontrol.svn_fs.* = disabled
    108 hgtrac.* = enabled
     112There's also a few Mercurial specific settings in TracIni:
     113{{{
     114[hg]
     115# -- Show revision number in addition to the changeset hash
     116show_rev = yes
     117
     118# -- Changeset hash format
     119node_format = short
     120# hex:   Show the full SHA1 hash
     121# short: Show a shortened hash for the changesets
    109122}}}
    110123
     
    113126
    114127The Mercurial support is pretty basic, but works well. I've tested that
    115 on the Mercurial repository itself and the performance is quite good,
     128on the Mercurial repository itself and the performance is acceptable,
    116129even if there's currently ''no'' caching in the database
    117 (I'm still not decided if that's a feature or a bug).
     130(this is what I'm going to work on next).
    118131
    119132For those used to Subversion in general and Subversion repository browsing
     
    140153
    141154Another additional changeset property is the list of ''Tags'' that
    142 might be associated with a changeset.
     155might be associated with a changeset.
     156
    143157
    144158==== Wiki syntax ====
     
    162176changeset without children): [[Image(hg-plugin-browser.png)]]
    163177
     178''has to be re-added''
    164179
    165180== Bugs and Limitations ==
     
    172187 * No ''path history'' mode (i.e. show all create/delete operations that
    173188   affected a given path)
     189 * Revision log ranges [xxx:yyy]
     190 * View arbitrary diffs
    174191
    175192=== Multi-repository support ===
     
    183200within a single environment (see #2086).
    184201
    185 
    186 === Arbitrary diff support ===
    187 
    188 The TracDiff features should be supported by TracMercurial too.
     202Note that the last comment on the above ticket suggests a good
     203workaround for this problem.
    189204
    190205
    191206=== To cache or not to cache? ===
    192207
    193 I happen to like to current database-free implementation of the Mercurial
    194 support.
    195 It makes it quite easy to change the `repository_dir` on the fly, and this
    196 flexibility is good. Also, hg being remarkably efficient, as everybody knows,
    197 the performance is quite good... Except in one case, getting the history
    198 of a directory. There, I suspect that the database cache would be quite useful.
    199 But I have yet to try on a big repository (e.g. the kernel) with either
    200 approach before concluding. In any case, thanks to the vc refactoring,
    201 the possibility will be offered to choose between a direct access or a
    202 cached access, as it's done for Subversion, svn: (cached) or
    203 direct-svn-fs: (direct access).
    204 
    205   ''cboos: I think I made up my mind, now that I tried to browse the kernel repo,
    206   it's way too slow without a db!
    207   Also, the way the diffs are produced currently (i.e. by Trac, from the full
    208   content of the files) is also too slow to be usable on such big repositories
    209   (e.g. the kernel changeset fc66195f585a took 7 minutes to be displayed on my
    210   machine). We need to get the diffs directly from hg.''
     208When you try TracMercurial on the kernel repo, you quickly realize
     209that it's way too slow without a db!
     210Also, the way the diffs are produced currently (i.e. by Trac, from the full
     211content of the files) is also too slow to be usable on such big repositories
     212(e.g. the kernel changeset fc66195f585a took 7 minutes to be displayed on my
     213machine).
     214See #2591.
    211215
    212216=== Cool Features ===
     
    237241== Implementation Notes ==
    238242
    239 I'm interested in feedback concerning the code, in particular:
    240  * concerning Trac, there are only a few changes to the standard modules,
    241    !ChangesetModule (the additional properties) and !BrowserModule
    242    (the tags and branches support). Those changes could possibly be promoted
    243    to the generic level, therefore removing the need for having to explicitely
    244    disable the SVN components...
    245  * concerning Mercurial, I'm pretty sure I did things in a sub-optimal
    246    way, as I was discovering the guts of hg while writing the plugin.
    247    Therefore, I'll be pleased to get tips for improvements.
     243I'm interested in feedback concerning the code, in particular
     244concerning Mercurial. I'm pretty sure I did things in a sub-optimal
     245way, as I was discovering the guts of hg while writing the plugin.
     246Therefore, I'll be pleased to get tips for improvements.
    248247
    249248'' -- ChristianBoos ''