= Revision Graph for the Version Control Browser = [[PageOutline]] == Description == This plugin renders a graphical representation of the repository. The plugin collects the repository's revisions and rebuilds the branches based on the names of the files changed in each revision. Filters can be used to choose which branches and which revisions are to be displayed. Each depicted changeset is a clickable item that redirects the browser to the appropriate changeset view. Whenever the mouse cursor is hovered over a revtree changeset, the browser opens a tool tip box that shows the revision number, the author and the date of the revision along with the wiki-formatted log message. The plugin also shows branch cloning/tagging operations, and can be extended to render other kinds of operations such as merging. [[Image(changeset-tip.png)]][[BR]] ''Changeset info tip'' == Overview == This plugin creates a graph that shows the changesets of the project repository. === Filters === The user may select which changesets are to be rendered, based on several filters: * The main filters are mutually exclusive: 1. '''changeset range''': this filter selects a range of changesets to be rendered 1. '''time range''': this filters selects the latest changesets of the repository, with the following predefined time ranges: * day, 2 days, 3 days, week, fortnight, month, 2 months, 3 months, year * Any of the following filters can be combined to the main filter to refine the selection: * '''branch name''': this filter selects a single branch, along with all branches declared as 'trunks' * '''author''': this filter selects all the branches for which the selected author has to be a participant (''i.e.'' has committed at least one changeset) * '''show terminated branches''': this filter makes all branches visible, including deleted ones. Default setting hides all ''terminated'' branches. [[Image(userprefs.png)]][[BR]] ''User preferences (filters)'' Two kinds of views can be selected: * '''compact''': in this mode, the revtree graph is kept as compact as possible, in an attempt to make all the changesets visible on the web browser page and thereby minimize the scrolling actions. Changesets are placed along on their branch, irrespectively of the nearby branches. * '''timeline''': in this mode, the revtree graph maintains a time view of the repository: each changeset can be seen relatively to the other changesets, whichever the changeset branch. ==== Example ==== [[Image(revtree2.png)]] === User preference persistence === The plugin stores the user settings (filters) in the user session, so the latest configuration is used whenever the user selects the 'revtree' page. In some cases, the chosen filters select no changeset hence no revtree graph can be rendered. In such an event, a Trac error is displayed with the following message: {{{ Selected filters cannot render a revision tree }}} User settings are not saved if the filter does not permit to generate a valid revtree graph. == Limitations == There are a lot of limitations, so read them carefully. 1. the RevtreePlugin generates inlined SVG. * SVG is only supported on modern browsers * ''inlined SVG'' means that the plugin generates XHTML+SVG data, which are only supported by a few browsers. Many browsers that support SVG do not accept ''inlined SVG''. Checkout the following section for a non-exhaustive list of supported browsers. 1. the RevtreePlugin only works with SVN repositories 1. it does not support SVN authz 1. it has not been thought with multiple projects per repository in mind, so its support for this kind of configuration is probably weak 1. filters do not support multiple selections: one can only select all or one branch, all or one author See RevtreePlugin/Limitations for a technical 'discussion' about the current limitations. The plugin output has been tested against the [http://validator.w3.org/check w3 validator] and generates ''Valid XHTML 1.1 plus MathML 2.0 plus SVG 1.1''. === Supported browsers === Any browser that supports ''inlined SVG'' should work. However, as it seems that some browsers are not able to cope with this kind of data, the following table sums up what you can expect from your favorite browser: '''Note:''' Support for !ReStructuredText is broken on Trac Hacks (see #1408), sorry for the matrix presentation {{{ #!rst +-----------+------------------+----------------+-----------+----------+---------------------------------------------------------------+ | OS + Browser + Version + Supported + SVG tree + Info Tips + Comments / Issues | +===========+==================+================+===========+==========+===========+===================================================+ | Windows | Firefox_ | 1.5, 2.0 |Not Tested | | | Gecko/1.8.1 | + + +----------------+-----------+----------+-----------+---------------------------------------------------+ | | | 3.0a5 |Not Tested | | | Infotips are not shown anymore (since 0.5.0) | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | IE_ + Adobe_ | 7.0 + 3.03 | No | | | Will never be supported (I just don't care) | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Opera_ | 9.21 |Not Tested | | | | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Safari_ | 3.0 beta |Not Tested | | | Beta release | +-----------+------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | OS X | Camino_ | 1.0.5 | Weak |Text is | Ok | Text not shown in SVG tree | + +------------------+----------------+ |not shown | | (known browser issue w/ SVG) | | | Firefox_ | 1.5, 2.0 | | | | | + + +----------------+-----------+----------+-----------+---------------------------------------------------+ | | | 3.0a5 |Incomplete | Ok | NO | Infotips are not shown, SVG elements are thick | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | OmniWeb_ | 5.5.4 | No |Text is | NO | Changeset text appears randomly, | | | | | |not shown | | info tips are not shown | + + +----------------+-----------+----------+-----------+---------------------------------------------------+ | | | 5.6pre | Yes | Ok | Ok | Browser not officially released yet (beta version)| | | | | | | | | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Opera_ | 9.21 | Yes | Ok | Ok | Slight display issue w/ info tip connectors | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Safari_ | 2.0.4 | No | NO | NO | Does not support SVG (will never be supported) | + + +----------------+-----------+----------+-----------+---------------------------------------------------+ | | | 3.0 522/11 | Yes | Ok | Ok | Beta release | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Webkit_ | r22084 | Yes | Text | Ok | Changeset text dissappears on scrolling | | | | | | issues | | (known browser issue w/ SVG) | +-----------+------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | Linux | Epiphany_ | 2.18.1 |Incomplete | Ok | No | Infotips are not shown | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Firefox_ | 2.0.0.4 | Yes | Ok | Ok | | + + +----------------+-----------+----------+-----------+---------------------------------------------------+ | | | 3.0a1 |Incomplete | Ok | No | Infotips are not shown | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Konqueror_ | 3.5.7 | No | No | No | The revision tree is not shown (inlined SVG does | | | | | | | | not seem to be supported), web engine is outdated | + +------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ | | Opera_ | 9.21 |Not Tested | n/a | n/a | Cannot run test: Opera crash in QT initialization | +-----------+------------------+----------------+-----------+----------+-----------+---------------------------------------------------+ .. _Adobe: http://www.adobe.com/svg/viewer/install .. _Camino: http://www.mozilla.org/camino .. _Epiphany: http://www.gnome.org/projects/epiphany .. _Firefox: http://www.mozilla.org/firefox .. _IE: http://www.microsoft.com/windows/ie .. _Konqueror: http://konqueror.kde.org .. _OmniWeb: http://www.omnigroup.com/applications/omniweb .. _Opera: http://www.opera.com .. _Safari: http://www.apple.com/safari .. _Webkit: http://webkit.org }}} The browser compatibility matrix has been created with RevtreePlugin 0.5.5 on June '07, 13^rd^ == Installation == === Get the plugin source code === ==== Download ==== Download the zipped source from [download:revtreeplugin here]. ==== Source ==== You can check out RevtreePlugin from [http://trac-hacks.org/svn/revtreeplugin here] using Subversion, or [source:revtreeplugin browse the source] with Trac. === Build the plugin === As with any other plugin: {{{ python setup.py bdist_egg }}} === Installation of the plugin === Copy the generated egg file (from the `dist/` directory) to your project plugin directory, or in the global plugin directory if you want to use it for several Trac projects === Enabling the plugin === From the WebAdmin plugin interface or from your trac.ini file, enable the RevtreePlugin. In `trac.ini`, edit the ''components'' section to add the revtree entry as follows: {{{ [components] revtree.* = enabled }}} === Configuration === The revtree plugin can be configured with the help of the following settings: * Mandatory parameters defined in the Trac section {{{ [trac] # SVN repositories only repository_type = svn # Base URL is a required parameter: it should be defined base_url = }}} ''Note'': `base_url` should not be left blank: it should be defined to the actual Trac URL, see [t:wiki:TracIni#trac-section TracIni] * Optional parameters defined in the `revtree` section {{{ [revtree] # regular expression for branch recognition # (always define 2 named groups: 'branch' and 'path') branch_re = ^(?Pbranches/[^/]+|trunk|tags)(?:/(?P.*))?$ # space-separated list of branches that should be considered as 'trunks' trunks = trunk # SVG rendering scale (real number) scale = 1.0 # oldest revision to consider (default to the latest revision in the repos) revbase = 1 # whether time filters are related to the youngest revision or # based on absolute time reltime = True # default appearance (either 'compact' or 'timeline') style = compact }}} Some settings deserve additional information: * the `style` option defines the default revtree graph style. Each user overwrites the default style the first time they update the revtree style. * the `reltime` option cannot be customized by the users. The admin chooses whether the time filters are based on the absolute time or the youngest changeset in the repository. Let's say the youngest revision in the repository has been committed three days ago: 1. if `reltime` is set, the revtree time ''starts'' three days ago as well: if the user selects the ''last 2 days'' as a filter, the last 5 days (3+2) will be shown 1. if `reltime` is not set, the revtree time ''starts'' now: if the user selects the ''last 2 days'', no changeset will be shown. ==== Repository layout adaptation ==== The default RevtreePlugin setting is defined to work with ''single-project'' repository layout, as defined in the Subversion book [http://svnbook.red-bean.com/nightly/en/svn.branchmerge.maint.html#svn.branchmerge.maint.layout repository layout] section. If your repository follows a different layout, you need to tweak the branch regex. The following regex would better match the ''multiple-project'' repository layout: {{{ branch_re = ^(?P[^/]+/(?:(?:tags|branches)/[^/]+|trunk))(?:/(?P.*))?$ }}} === Revtree menu item === You can change the position of the ''revtree'' menu item using the Trac `mainnav` setting, see [t:wiki:TracIni#trac-section TracIni]. For example, to make the ''revtree'' menu item appear at the right hand side of the ''browser'' item, update the `mainnav` line as follows: {{{ [trac] mainnav = wiki,timeline,roadmap,browser,revtree,tickets,newticket,search }}} === Permissions === The RevtreePlugin defines a new permission `REVTREE_VIEW`. This permission should be defined for the 'revtree' link to appear in the main navigation bar, and to give access to the revtree feature. === Restarting trac === You need to restart your web server to make the changes effective. == Revision tree enhancements == The RevtreePlugin has been written with customization in mind: it provides extension points so that one can write his own plugin(s) to add information to the rendered graph and enhance it. For now, there are two ways to enhance the revision tree graph: * Change the appearance of the rendered items, and add ''operations'' to the graph. An operation is a relation between two distinct branches, such as a merge operation.[[BR]] -> this extension point is dedicated to provide operations that are not maintained by the underlying repository. These operations can be stored in revision properties, log message, or any other way: it depends on how a team use the repository. * Improve the branch placement. One of the most difficult task to draw a graphical representation of the repository is to find the best location for each branch. The ''best'' location depends on how a team work, what is the most important information to be represented, and to limit the number of operation intersections as much as possible.[[BR]] -> this extension point allows custom branch sorting. There are probably smart algorithms that could allow better branch placement. === Default enhancers === The RevtreePlugin comes with default enhancers: * !SimpleEnhancer is a very basic enhancer that is only able to cope with branch creation and tagging. * It uses a dummy placement algorithm, which places the trunk at the center of the graph, and tries to reduce the number of operation intersections. === More enhancers === The RevtreePlugin/LogEnhancer plugin is provided as an implementation example of the first kind of enhancer. (More technical doc to come about how to write your own enhancers) == Miscelleanous == === Recent Changes === See RevtreePlugin/Changelog Since version 0.5.0, only Trac [t:milestone:0.11 0.11] is supported.[[BR]] Previous releases are still available for download, but are not maintained. Version 0.5.0 and above cannot be used with Trac [t:milestone:0.10 0.10] as it requires the [http://genshi.edgewall.org Genshi] library and uses Trac internal APIs that have changed since the previous release. ==== Additional notes ==== Note that several API breaks are expected in Trac [t:milestone:0.11 0.11], which may occasionally break this plugin. Be sure to upgrade your Trac trunk to the latest available release before reporting an incident issue w/ this plugin. Do not forget to flush your browser cache when you update the RevtreePlugin. Several browsers fail to reload CSS and/or Javascript files properly, which may appear as plugin errors. === What about the original revtree plugin? === It supersedes the SvnCcHelpersScript/RevTree plugin: 1. it does not rely on any Clearcase external scripts nor on any SVN custom properties to build the graph, 1. it does not use the GraphvizPlugin nor the Graphviz (''dot'') tool to render the graph. It is a pure Python implementation, 1. it uses the Trac repository cache, which dramatically speeds up the generation of the graph 1. it can be configured and extended to support custom repository organization The older plugin code has been removed from the TracHacks.org repository. == Bugs/Feature Requests == Existing bugs and feature requests for RevtreePlugin are [report:9?COMPONENT=RevtreePlugin here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=RevtreePlugin&owner=eblot new ticket]. === Author/Contributors === Authors:: [wiki:eblot] Contributors:: === Libraries === The RevtreePlugin uses the following libraries: * [http://genshi.edgewall.org Genshi], the XML templating system used in Trac * [http://jquery.com/ Jquery] a lightweight, yet powerful Javascript library * [http://www2.sfk.nl/svg SVGdraw] is a Python library that enables SVG generation