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 | |
| 5 | This a plugin for Trac which enables [http://www.selenic.com/mercurial Mercurial] to be used as the VersionControlSystem for Trac. |
| 6 | |
| 7 | Please use a recent version of the plugin before reporting issues. |
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 | |
| 80 | Then 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 |
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/ |
| 103 | see [http://selenic.com/pipermail/mercurial/2007-July/013827.html this mail]. |
| 104 | However, 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 | |
| 108 | Alternatively, you can install the pre-built Mercurial Python modules from http://bitbucket.org/tortoisehg/thg-winbuild/downloads/ |
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 | |
| 114 | The 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. |
| 115 | Thanks 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 | |
| 119 | The 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 | |
| 121 | If 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. |
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 | |
| 131 | You can either reuse an existing Trac environment or create a new one. For general instructions, see TracInstall. |
| 132 | |
| 133 | When creating a new environment with TracAdmin `initenv` command: |
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 | |
| 187 | Mercurial 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 | |
| 189 | For 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 | |
| 195 | In Mercurial, the ''Previous Changeset''/''Next Changeset'' navigation is ''not'' purely sequential, as it is in Subversion. |
| 196 | Instead of a ''flat'' history of successive changesets, we actually navigate a [http://en.wikipedia.org/wiki/Directed_acyclic_graph DAG] of changesets. |
| 197 | This means a changeset can have multiple parents (0, 1 or 2) and multiple children as well (0 to n). |
| 198 | |
| 199 | Therefore, ''Previous Changeset'' is a link to the first parent, and ''Next Changeset'' is a link to the first child. |
| 200 | In 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. |
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 ... |
| 204 | Another additional changeset property is the list of ''Tags'' that might be associated with a changeset. |
| 205 | |
| 206 | ==== Wiki syntax |
| 207 | |
| 208 | The 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. |
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 | | ---- |
| 210 | Also, it is possible to refer to changesets using the changeset: prefix, or cset: or chgset:, for hgweb compatibility. |
| 211 | The tag: prefix can be used to refer to symbolic tags, although this is not a requirement, because using `cset:tip` would work too. |
| 212 | Finally, 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 | |
| 216 | The 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 | |
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 | |
| 232 | There 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. |
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 | |
| 244 | While 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 |
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? |
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. |
| 307 | 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. |