Edgewall Software

Changes between Version 102 and Version 103 of TracMercurial


Ignore:
Timestamp:
Apr 16, 2015, 8:57:08 PM (7 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • TracMercurial

    v102 v103  
    11[[PageOutline(2-3)]]
    2 = Mercurial Plugin for Trac (#1847) =
    3 
    4 This a plugin for Trac which enables
    5 [http://www.selenic.com/mercurial Mercurial]
    6 to be used instead of [http://subversion.tigris.org Subversion]
    7 as the VersionControlSystem for Trac.
    8 
    9 Please take care to use a recent version of the plugin before reporting issues.
     2
     3= Mercurial Plugin for Trac (#1847)
     4
     5This a plugin for Trac which enables [http://www.selenic.com/mercurial Mercurial] to be used as the VersionControlSystem for Trac.
     6
     7Please use a recent version of the plugin before reporting issues.
    108See the [#Releases version table] below.
    119
    12 The mercurial plugin for Trac is now hosted in its own Mercurial repository, [repos:mercurial-plugin] (it was about time!)
    13 {{{
     10The Mercurial plugin for Trac is now hosted in its own Mercurial repository, [repos:mercurial-plugin]:
     11{{{#!sh
    1412hg clone https://hg.edgewall.org/trac/mercurial-plugin
    1513}}}
     
    2523   - log:plugins/0.11/mercurial-plugin, see [./@90#Trac0.11 Trac 0.11] and [./@89#Settingupthemercurialplugin setting up the plugin for 0.11]
    2624
    27 
    28 == Download and Installation ==
     25== Download and Installation
    2926
    3027=== Releases and compatibility matrix   #Releases
    3128
    3229{{{#!table class="listing"
    33 ||=  '''Version'''  =||=  mercurial-plugin  =||=  Trac  =||=  Compatible with hg  =||
     30||=  '''Version'''  =||=  '''mercurial-plugin'''  =||=  '''Trac'''  =||=  '''Compatible with hg'''  =||
    3431|| **1.0.0.4** ||\
    3532|| **[source:mercurial-plugin@c91c42e]** ([source:mercurial-plugin@1.0 1.0] branch) [attachment:TracMercurial-1.0.0.4-py2.7.egg .egg] ||\
     
    6764}}}
    6865
    69 
    70 === Trac ===
    71 
    72 Consult the version table [#Releases below] to check which precise 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.
    73 
    74 Installation of the plugin:
    75 {{{
     66=== Trac
     67
     68Consult the version table [#Releases below] 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.
     69
     70Installation of the plugin, depending on the version of Trac you are using:
     71{{{#!sh
    7672hg clone http://hg.edgewall.org/trac/mercurial-plugin#0.12
    7773}}}
     74
    7875or:
    79 {{{
     76{{{#!sh
    8077hg clone http://hg.edgewall.org/trac/mercurial-plugin#1.0
    8178}}}
    82 depending on the version of Trac you're using ([source:branches/0.12-stable 0.12] or [source:branches/1.0-stable 1.0]) (also use 1.0 for trunk).
    83 
    84 Then from the checkout (`cd mercurial-plugin`), you have various installation options:
    85  - create an "egg" which you can copy to your `$TRACENV/plugins`, for example:
    86    {{{
    87    $ python setup.py bdist_egg
     79
     80Then from the checkout (`cd mercurial-plugin`), you have the following installation options:
     81 - Create an "egg" which you can copy to your `$TRACENV/plugins`:
     82   {{{#!sh
     83   python setup.py bdist_egg
    8884   }}}
    89  - install it in the current Python (or [http://pypi.python.org/pypi/virtualenv virtualenv]) installation:
    90    {{{
    91    $ python setup.py install
     85 - Install it in the current Python (or [http://pypi.python.org/pypi/virtualenv virtualenv]) installation:
     86   {{{#!sh
     87   python setup.py install
    9288   }}}
    93  - similar to the above, but directly use the code from the checkout (ideal for hacking):
    94    {{{ 
    95    $ python setup.py develop
     89 - Similar to the above, but directly use the code from the checkout (ideal for hacking):
     90   {{{#!sh
     91   python setup.py develop
    9692   }}}
    9793
    98 
    99 
    100 === Mercurial ===
    101 
    102 You can download Mercurial itself from
    103 [http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
    104 
    105 We try to maintain backward compatibility with versions of Mercurial as old as 1.1,
    106 up to the latest. Better use a recent version however.
     94=== Mercurial
     95
     96You can download Mercurial itself from [http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
     97
     98We try to maintain backward compatibility with versions of Mercurial as old as 1.1, up to the latest. Better use a recent version however.
    10799
    108100==== Windows
     101
    109102On Windows, it looks like it's possible to re-use the Mercurial library coming from the [Mercurial:BinaryPackages installer],
    110 see [http://selenic.com/pipermail/mercurial/2007-July/013827.html this mail]
    111 (though to my knowledge, 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).
    112 
    113 ''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).
    114 
    115 Alternatively you can install the pre-built Mercurial Python modules from http://bitbucket.org/tortoisehg/thg-winbuild/downloads/
     103see [http://selenic.com/pipermail/mercurial/2007-July/013827.html this mail].
     104However, 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.
     105
     106'''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).
     107
     108Alternatively, you can install the pre-built Mercurial Python modules from http://bitbucket.org/tortoisehg/thg-winbuild/downloads/
    116109
    117110You may also want to experiment with the newly introduced Mercurial:HackableMercurial distribution.
    118111
    119 == Configuration ==
    120 
    121 The configuration has to be done on the Trac side,
    122 there's nothing to do on the Mercurial repository side,
    123 except for the fact that the repository should be made
    124 accessible as a local repository.
    125 Thanks to the distributed nature of Mercurial, that's
    126 always possible (if the repository is not already local,
    127 simply `hg clone` it).
    128 
    129 
    130 === Setting up the mercurial plugin ===
    131 
    132 The TracMercurial plugin egg should be added to the `plugins` folder of the
    133 environment, or it can be globally installed (`python setup.py install`
    134 or a `python setup.py develop`).
    135 
    136 For general instructions about plugins, see also TracPlugins.
    137 
    138 If you installed the egg globally and you're modifying an
    139 existing Trac environment to use the Mercurial backend,
    140 then you have to explicitly ''enable'' the plugin in TracIni.
     112== Configuration
     113
     114The 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.
     115Thanks to the distributed nature of Mercurial, that's always possible. If the repository is not already local, simply `hg clone` it.
     116
     117=== Setting up the Mercurial plugin
     118
     119The 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.
     120
     121If you installed the egg globally and you're modifying an existing Trac environment to use the Mercurial backend, then you have to explicitly ''enable'' the plugin in TracIni.
    141122
    142123Since the version 0.11 of the plugin, the package has been renamed to `tracext`:
    143 {{{
     124{{{#!ini
    144125[components]
    145126tracext.hg.* = enabled
    146127}}}
    147128
    148 === Setting up a Trac environment ===
    149 
    150 You can either reuse an existing Trac environment,
    151 or create a brand new one.
    152 
    153 For general instructions, see TracInstall.
    154 
    155 When creating a new environment with TracAdmin `initenv` command,
     129=== Setting up a Trac environment
     130
     131You can either reuse an existing Trac environment or create a new one. For general instructions, see TracInstall.
     132
     133When creating a new environment with TracAdmin `initenv` command:
    156134 - for the ''repository type'', specify `hg` instead of the default `svn`.
    157  - for the ''repository directory'', specify the location of the Mercurial repository
    158    (without the ending `.hg`).
    159 
    160 Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file
    161 should have a `[trac]` section similar to the following:
     135 - for the ''repository directory'', specify the location of the Mercurial repository, without the ending `.hg`.
     136
     137Your [wiki:TracIni <trac_environment>/conf/trac.ini] configuration file should have a `[trac]` section similar to the following:
    162138{{{#!ini
    163139[repositories]
     
    166142}}}
    167143
    168 There's also a few Mercurial specific settings in TracIni:
    169 {{{
     144There are also a few Mercurial specific settings in TracIni:
     145{{{#!ini
    170146[hg]
    171147# -- Show revision number in addition to the changeset hash (defaults to yes)
     
    178154}}}
    179155
    180 === Setting up post-commit hooks ===
     156=== Setting up post-commit hooks
     157
    181158For [milestone:0.12] and later:
    182159
     
    199176Remember 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.
    200177
    201 You must also enable the CommitTicketUpdater functionality in your `trac.ini` by adding
    202 
    203 {{{
     178You must also enable the CommitTicketUpdater functionality in your `trac.ini`:
     179
     180{{{#!ini
     181[components]
    204182tracopt.ticket.commit_updater.* = enabled
    205183}}}
    206184
    207 to the `[components]` section.
    208 
    209 == Features ==
    210 
    211 The Mercurial support is pretty basic, but works well. I've tested that
    212 on the Mercurial repository itself and the performance is acceptable,
    213 even if there's currently ''no'' caching in the database
    214 (this is what I'm going to work on next, with a very loose definition of next, see #8417).
    215 
    216 For those used to Subversion in general and Subversion repository browsing
    217 in Trac in particular, there are a few differences worth noting.
    218 
    219 === Mercurial Changesets ===
    220 
    221 ==== Changeset Navigation ====
    222 
    223 In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is
    224 ''not'' purely sequential, as it is in Subversion.
    225 Instead of a ''flat'' history of successive changesets, we actually navigate
    226 a DAG of changesets.
    227 This means a changeset can have multiple parents (0, 1 or 2) and multiple
    228 children as well (0 to n).
    229 
    230 Therefore, ''Previous Changeset'' is a link to the first parent,
    231 and ''Next Changeset'' is a link to the first child.
    232 In case there are additional parents or children, these are shown as
    233 additional changeset properties (''Parents'' or ''Children''),
    234 placed below the ''Author'' property and above the ''Message'' property.
     185== Features
     186
     187Mercurial support is basic, but works well. I've tested that on the Mercurial repository itself and the performance is acceptable, even if there's currently ''no'' caching in the database, see #8417.
     188
     189For those used to Subversion in general and Subversion repository browsing in Trac in particular, there are a few differences worth noting.
     190
     191=== Mercurial Changesets
     192
     193==== Changeset Navigation
     194
     195In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is ''not'' purely sequential, as it is in Subversion.
     196Instead of a ''flat'' history of successive changesets, we actually navigate a [http://en.wikipedia.org/wiki/Directed_acyclic_graph DAG] of changesets.
     197This means a changeset can have multiple parents (0, 1 or 2) and multiple children as well (0 to n).
     198
     199Therefore, ''Previous Changeset'' is a link to the first parent, and ''Next Changeset'' is a link to the first child.
     200In 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.
    235201
    236202[[Image(hg-plugin-changeset.png,width=666px,align=center)]]
    237203
    238 Another additional changeset property is the list of ''Tags'' that
    239 might be associated with a changeset.
    240 
    241 
    242 ==== Wiki syntax ====
    243 
    244 The Wiki syntax has been extended a bit, to cope with the hexadecimal
    245 notation of hg changesets. E.g. `[8ef2]` would link to the changeset
    246 8ef2ba892518c115170398ec754bd1c27cab271f ...
     204Another additional changeset property is the list of ''Tags'' that might be associated with a changeset.
     205
     206==== Wiki syntax
     207
     208The Wiki syntax has been extended a bit, to cope with the hexadecimal notation of hg changesets. For example, `[8ef2]` would link to the changeset 8ef2ba892518c115170398ec754bd1c27cab271f.
    247209Plain changeset numbers are also recognized, provided they are long enough (12 to 40).
    248 Also, it is possible to refer to changesets using the changeset: prefix
    249 (or cset: or chgset:, for hgweb compatibility).
    250 The tag: prefix can be used to refer to symbolic tags, although this is not
    251 a requirement (using. e.g. `cset:tip` would work too).
    252 Finally, the branch: prefix has a special meaning, as this will not select
    253 the specified revision, but the head which is reachable from that revision.
    254 
    255 
    256 === TracBrowser changes in [milestone:0.11] ===
    257 
    258 The TracBrowser ''View revision'' form has been extended with
    259 pulldown menus for jumping to a given tag or branch (in Mercurial,
    260 a branch within a repository corresponds to a head, i.e. a
    261 changeset without children):
    262 ----
     210Also, it is possible to refer to changesets using the changeset: prefix, or cset: or chgset:, for hgweb compatibility.
     211The tag: prefix can be used to refer to symbolic tags, although this is not a requirement, because using `cset:tip` would work too.
     212Finally, the branch: prefix has a special meaning, as this will not select the specified revision, but the head which is reachable from that revision.
     213
     214=== TracBrowser changes in [milestone:0.11]
     215
     216The TracBrowser ''View revision'' form has been extended with pulldown menus for jumping to a given tag or branch. In Mercurial, a branch within a repository corresponds to a head, i.e. a changeset without children:
     217
    263218[[Image(hg-plugin-browser.png,width=666px,align=center)]]
    264 ----
    265 There's also support for visual ''blame'' annotations:
    266 ----
     219
     220There is also support for visual ''blame'' annotations:
     221
    267222[[Image(hg-plugin-annotate.png,width=666px,align=center)]]
    268223
    269 === Mercurial Queue ===
     224=== Mercurial Queue
    270225
    271226Since r6443, the MQ extension is supported. If you happen to have applied mq patches in your repository, Trac will show the corresponding patch names as '''Tags:''' in the changeset view.
     
    273228Also, 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 (i.e. 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).
    274229
    275 === Cool Features ===
    276 
    277 ''Wild ideas'' section...
    278 
    279 ==== Visualize branches and merges ====
    280 
    281 There should be a way to show graphically the branch and merge points within
    282 the revision log view. Not something as fancy as `hgk`, but nonetheless
    283 something that will make the changeset relationships immediately obvious.
     230==== Visualize branches and merges
     231
     232There 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.
    284233
    285234''Starting with Trac [milestone:0.13], we show a graphical overview of the branch graph when viewing the log of the repository root (#1492)''
     
    287236Also, there is [http://trac-hacks.org/wiki/RevtreePlugin RevtreePlugin].
    288237
    289 ==== Search over the source ====
     238==== Search over the source
    290239
    291240A search provider could do the equivalent of an `hg grep`.
    292241
    293 ==== Highlight Conflict Resolution ====
    294 
    295 While visualizing changeset diffs for merge changesets, we already
    296 show the changes relative to both parents, which helps to understand
    297 how conflicts (if any) were solved. But this can be improved by
    298 specifically highlighting lines that differs from both parents.
    299 
    300 ==== Repository Management ====
     242==== Highlight Conflict Resolution
     243
     244While 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 differs from both parents.
     245
     246==== Repository Management
    301247
    302248Trac should allow for creating new repositories or clones of existing repositories. Maybe repository deletion and renaming should be supported, too.
    303249
    304 ==== ~~HG Forest Support~~ Subrepositories support ====
     250==== Subrepositories support
    305251
    306252//The forest extension has been superseded by support for [Mercurial:Subrepository nested repositories]. Replace //forest// below by //subrepository//.// (#9704)
     
    313259 ''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.''
    314260
    315 ==== ''Add your cool feature here...'' ====
     261==== Add your requested feature here
     262
    316263[[TicketQuery(component=plugin/mercurial,milestone=plugin - mercurial,status=!closed,type=enhancement)]]
    317264
    318 
    319 == Bugs and Limitations ==
    320 
    321 There are still a lot of things that can be improved.
    322 
    323 === Features that Trac+svn has but not currently implemented for Trac+hg ===
    324 
    325  * No ''path history'' mode (i.e. show all create/delete operations that
    326    affected a given path)
    327 
    328 === To cache or not to cache? ===
     265== Bugs and Limitations
     266
     267=== Features that Trac+svn has but not currently implemented for Trac+hg
     268
     269 * No ''path history'' mode, ie show all create/delete operations that affected a given path.
     270
     271=== To cache or not to cache?
    329272
    330273Recent 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.
     
    355298[[TicketQuery(component=plugin/mercurial,milestone=plugin - mercurial,status=!closed,type=defect)]]
    356299
    357 == Implementation Notes ==
     300== Implementation Notes
    358301
    359302Hacking on Mercurial:
     
    362305 - [mercurial:CommandServer] and [mercurial:PythonHglib] (not yet used - see #10411)
    363306
    364 I'm interested in feedback concerning the code, in particular
    365 concerning Mercurial. I'm pretty sure I did things in a sub-optimal
    366 way, as I was discovering the guts of hg while writing the plugin.
    367 Therefore, I'll be pleased to get tips for improvements.
     307I'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.
    368308
    369309'' -- ChristianBoos ''