Context Navigation

Changes between Version 14 and Version 15 of TracMercurial

Timestamp:: Feb 14, 2006, 4:46:53 PM (18 years ago)
Author:: Christian Boos
Comment:: Update the documentation so that it matches the current implementation.

Legend:

: Unmodified
: Added
: Removed
: Modified

TracMercurial

-              v14
+              v15
 = Mercurial Plugin for Trac (#1847) =
 There is an '''experimental''' plugin for Trac [milestone:0.9] which enables
 [http://www.selenic.com/mercurial Mercurial] to be used
 instead of [http://subversion.tigris.org Subversion]
 for the VersioningSystemBackend.
+There is an '''experimental''' plugin for Trac [milestone:0.10]
+which enables [http://www.selenic.com/mercurial Mercurial]
+to be used instead of [http://subversion.tigris.org Subversion]
+as the VersioningSystemBackend for Trac.
 ''The plugin being experimental, expect some rough edges
 and a somewhat unstable set of features/documentation...''
+Change Logs:
+ * log:sandbox/mercurial-plugin
+ * log:sandbox/vc-refactoring
 == Download and Installation ==
 ==== Trac ====
+The plugin needs a slightly modified version of Trac 0.9,
+which offers support for pluggable SCM backends.
+The plugin needs a slightly modified version of Trac 0.10.
 This version can be found in source:sandbox/vc-refactoring.
-It has been partially ported to trunk and retired since,
-but for TracMercurial, you still need the ''original''
-`vc-refactoring` branch, at revision 2620.
 Simply do:
 {{{
+svn co -r2620
+http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring trac-for-hg
+}}}
+and install from there (`cd trac-for-hg; python setup.py install`).
+svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring
+}}}
+and install from there:
+{{{
+$ cd vc-refactoring
+$ python setup.py egg_info
+$ python setup.py install
+}}}
 The plugin itself is available from source:sandbox/mercurial-plugin
 …
 Check it out, too:
 {{{
 svn co -r2620 http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin mercurial-plugin
+svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin
 }}}
 and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`).
 Note that you'll need
 [http://peak.telecommunity.com/DevCenter/setuptools setuptools]
 >= 0.6 for that (I used setuptools-0.6a5).
+>= 0.6 for that (I used setuptools-0.6a9).
 ===== Releases =====
 || '''Version''' || mercurial-plugin || Trac vc-refactoring || Compatible with hg         ||
 ||      0.1      ||       r2514      ||        r2511        ||  0.7, tip without 1d7d0c07 ||
+||               ||    '''r2620'''   ||     '''r2620'''     ||  0.7, tip with 1d7d0c07    ||
+||               ||       r2620      ||        r2620        ||  0.7, tip with 1d7d0c07    ||
+||   '''0.2'''   ||    '''r2905'''   ||     '''r2905'''     ||  0.7, 0.8, tip  ||
 ==== Mercurial ====
 The plugin has been tested with recent development versions of Mercurial
 (upto Changeset 1568:1d7d0c07e8f3 from http://selenic.com/hg)
 and also Mercurial 0.7 (but this needs at least r2514 of the mercurial plugin).
 ''It won't work with earlier versions.''
 You can download hg from
+(upto Changeset 1704:c2755eba8631 from http://selenic.com/hg)
+and also with Mercurial 0.7 and 0.8.
+''It won't work with earlier versions, in particular not with 0.6x.''
+You can download Mercurial itself from
 [http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
 …
 The configuration has to be done on the Trac side,
 there's nothing to do on the Mercurial repository side,
+except that it should be made available locally.
+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-0.2 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're modifying an
+existing Trac environment to use the Mercurial backend,
+then you have to explicitely ''enable'' the plugin in TracIni:
+{{{
+[components]
+trac.versioncontrol.hg.* = enabled
+}}}
+Note that the above will be done automatically for a new installation,
+during the `initenv` step.
 === Setting up a Trac environment ===
 …
 For general instructions, see TracInstall.
+The TracAdmin `initenv` command has been slightly modified
+in the vc-refactoring code base: in addition to the
+''repository directory'', it's also needed to specify the
+''repository type''.
+Since milestone:0.10, the TracAdmin `initenv` command has
+now a ''repository type'' argument besides ''repository directory''.
 For the ''repository type'', specify `hg` instead of the default `svn`.
+For the ''repository directory'', specify the location of the Mercurial repository.
+In all case, you [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
+For the ''repository directory'', specify the location of the Mercurial repository
+(without the ending `.hg`).
+Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
 should have a `[trac]` section similar to the following:
 {{{
 …
 }}}
+''Note: those installing from 0.9 + the patch on #1847 will still have to specify `repository_dir=hg:/path/to/my/hg/repository`''
+Also, currently you still need to explicitely disable the SVN components:
+{{{
+[components]
+trac.versioncontrol.svn_fs.* = disabled
+}}}
+''Note: that constraint will most certainly be lifted in the future''
+=== Setting up the mercurial plugin ===
+The TracMercurial-0.1 plugin egg should be added to the `plugins` folder of the
+environment.
+For general instructions about plugins, see also TracPlugins.
+Finally, if you installed an unpacked egg by doing a `python setup.py install`
+(useful for development), there's the additional constraint of specifically
+''enabling'' the plugin:
+{{{
+[components]
+trac.versioncontrol.svn_fs.* = disabled
+hgtrac.* = enabled
+There's also a few Mercurial specific settings in TracIni:
+{{{
+[hg]
+# -- Show revision number in addition to the changeset hash
+show_rev = yes
+# -- Changeset hash format
+node_format = short
+# hex:   Show the full SHA1 hash
+# short: Show a shortened hash for the changesets
 }}}
 …
 The Mercurial support is pretty basic, but works well. I've tested that
 on the Mercurial repository itself and the performance is quite good,
+on the Mercurial repository itself and the performance is acceptable,
 even if there's currently ''no'' caching in the database
 (I'm still not decided if that's a feature or a bug).
+(this is what I'm going to work on next).
 For those used to Subversion in general and Subversion repository browsing
 …
 Another additional changeset property is the list of ''Tags'' that
+might be associated with a changeset.
+might be associated with a changeset.
 ==== Wiki syntax ====
 …
 changeset without children): [[Image(hg-plugin-browser.png)]]
+''has to be re-added''
 == Bugs and Limitations ==
 …
  * No ''path history'' mode (i.e. show all create/delete operations that
    affected a given path)
+ * Revision log ranges [xxx:yyy]
+ * View arbitrary diffs
 === Multi-repository support ===
 …
 within a single environment (see #2086).
+=== Arbitrary diff support ===
+The TracDiff features should be supported by TracMercurial too.
+Note that the last comment on the above ticket suggests a good
+workaround for this problem.
 === To cache or not to cache? ===
+I happen to like to current database-free implementation of the Mercurial
+support.
+It makes it quite easy to change the `repository_dir` on the fly, and this
+flexibility is good. Also, hg being remarkably efficient, as everybody knows,
+the performance is quite good... Except in one case, getting the history
+of a directory. There, I suspect that the database cache would be quite useful.
+But I have yet to try on a big repository (e.g. the kernel) with either
+approach before concluding. In any case, thanks to the vc refactoring,
+the possibility will be offered to choose between a direct access or a
+cached access, as it's done for Subversion, svn: (cached) or
+direct-svn-fs: (direct access).
+  ''cboos: I think I made up my mind, now that I tried to browse the kernel repo,
+  it's way too slow without a db!
+  Also, the way the diffs are produced currently (i.e. by Trac, from the full
+  content of the files) is also too slow to be usable on such big repositories
+  (e.g. the kernel changeset fc66195f585a took 7 minutes to be displayed on my
+  machine). We need to get the diffs directly from hg.''
+When you try TracMercurial on the kernel repo, you quickly realize
+that it's way too slow without a db!
+Also, the way the diffs are produced currently (i.e. by Trac, from the full
+content of the files) is also too slow to be usable on such big repositories
+(e.g. the kernel changeset fc66195f585a took 7 minutes to be displayed on my
+machine).
+See #2591.
 === Cool Features ===
 …
 == Implementation Notes ==
+I'm interested in feedback concerning the code, in particular:
+ * concerning Trac, there are only a few changes to the standard modules,
+   !ChangesetModule (the additional properties) and !BrowserModule
+   (the tags and branches support). Those changes could possibly be promoted
+   to the generic level, therefore removing the need for having to explicitely
+   disable the SVN components...
+ * 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.
+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 ''