- Bugs/Feature Requests
- Revision tree enhancements
- Recent Changes
Revision Graph for the Version Control Browser
This plugin renders a graphical representation of the changesets of the project 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.
Changeset info tip:
The user may select which changesets are to be rendered, based on several filters:
- The main filters are mutually exclusive:
- changeset range: this filter selects a range of changesets to be rendered
- 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 (ie has committed at least one changeset)
- show terminated branches: this filter makes all branches visible, including deleted ones. Default setting hides all terminated branches.
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, irrespective 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.
See revtree-stresstest.png for a sample image of the timeline mode with about 300 changesets.
The timeline view will look as follows:
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.
This plugin has the following known limitations:
RevtreePlugin assumes that each revision contains changes in a single branch - and only one. If it's not the case, RevtreePlugin may not work or behave unpredictably. See #1090 and #1191 for details about this design choice, as well as #1354 and #1635.
CVS switchers, please be sure to read the dedicated section.
- the RevtreePlugin generates inlined SVG.
- SVG is supported on most modern browsers
- inlined SVG means that the plugin generates XHTML+SVG data, which are 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.
- the RevtreePlugin only works with SVN repositories.
- it does not support SVN authz.
- it has not been thought with multiple projects per repository in mind, so its support for this kind of configuration is probably weak.
- 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 W3 Validator and generates Valid XHTML 1.1 plus MathML 2.0 plus SVG 1.1.
Any browser that supports inlined SVG should work. However, for those browsers that do not, the following table sums up what you can expect compatibility matrix. This matrix has been created with RevtreePlugin 0.5.15 on 17-Apr-2008.
If you have any issues, create a new ticket.
Download the zipped source from here.
The RevtreePlugin uses the following libraries:
- Genshi, the XML templating system used in Trac.
- SVGdraw is a Python library that enables SVG generation. User Note: Seems to be included, and is nowhere else in Google.
To build the plugin, run setup.py:
python setup.py bdist_egg
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.
From the WebAdmin plugin interface or from your
trac.ini file, enable the RevtreePlugin.
trac.ini file, edit the components section to add the revtree entry as follows:
[components] revtree.* = enabled
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 =
base_urlshould not be left blank: it should be defined to the actual Trac URL, see TracIni.
- Optional parameters are defined in the
[revtree] # regular expression for branch recognition # (always define 2 named groups: 'branch' and 'path') branch_re = ^(?P<branch>branches/[^/]+|trunk|tags)(?:/(?P<path>.*))?$ # 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 start on absolute time or on the time of the youngest revision abstime = True # default appearance (either 'compact' or 'timeline') style = compact # revtree item appears as the main menu contexts =
Some settings deserve additional information:
styleoption defines the default revtree graph style. Each user overwrites the default style the first time they update the revtree style.
reltimeoption 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:
reltimeis 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
reltimeis not set, the revtree time starts now: if the user selects the last 2 days, no changeset will be shown.
Repository layout adaptation
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<branch>[^/]+/(?:(?:tags|branches)/[^/]+|trunk))(?:/(?P<path>.*))?$
Revtree menu item
Revtree menu may either appears as a main menu item, ie in the menu bar, or as a contextual menu item.
- to make revtree link appear as a contextual menu item, define a
contextsoption in the
[revtree]section of your
trac.inifile and use a comma-separated list of the page contexts where the revtree menu should appear:makes revtree links appear in the Changeset navigation bar and the Browser navigation bar:
[revtree] contexts = changeset, browser
- to revert to the default settings, that is make Revtree to appear within the main menu bar, simply remove the
contextsoption from your config file:
Position in the main menu
You can change the position of the revtree menu item using the Trac
mainnav setting, see 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
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.
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.
-> 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 uses the repository.
- Improve the branch placement. One of the most difficult tasks 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 works, what is the most important information to be represented, and to limit the number of operation intersections as much as possible.
-> this extension point allows custom branch sorting. There are probably smart algorithms that could allow better branch placement.
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.
Enhancers based on log messages
- the RevtreePlugin/LogEnhancer plugin is provided as an implementation example of the first kind of enhancer. It uses special keywords in the log messages to augment the revtree graph with branch creation, termination and merge operations.
Enhancers based on SVN properties
- the RevtreePlugin/MergeInfoEnhancer plugin can be used with the latest SVN release (SVN >= 1.5) to show the inter-branch merge operations of a repository. It is in early development stage and may not be reliable.
- the RevtreePlugin/MergeEnhancer plugin can be used in conjunction with the svnmerge tool to show the inter-branch merge operations of a repository. This enhancer is not actually maintained and is provided as an example of enhancer implementation.
SVN repository imported from CVS
I never used
cvs2svn myself, but the following information might be useful for those who want to import their CVS-managed source code into a new SVN repository, and still be able to browse the repository with the RevtreePlugin. Thanks to Marcio Marchini for providing these tips:
It is perfectly possible to make cross-branch commits using CVS and Subversion, so by default when cvs2svn sees what looks like a CVS cross-branch commit, it converts it as a Subversion cross-branch commit.
But you can use a switch in the options file to choose different behavior. See the following section in cvs2svn-example.options:
# To prevent CVS commits from different projects from being merged # into single SVN commits, change this option to False: ctx.cross_project_commits = True # To prevent CVS commits on different branches from being merged into # single SVN commits, change this option to False: ctx.cross_branch_commits = True
If you want to use your project with Revtree, you should set both of these options to False.
If you have already used your converted repository for a while, then you already have commits on top of the ones generated by cvs2svn and it would be very difficult to change your repository retroactively. It could possibly be done by re-converting with cvs2svn, "svnadmin dump"ing the post-conversion commits to a dumpfile, hacking the dumpfile to fix the revision numbers that it refers to, then "svnadmin load"ing the dumpfile onto the newly-converted repository.
It seems that
cvs2svn enclines to generate changesets that Subversion APIs fail to describe properly. See #1638.
What about the original revtree plugin?
It supersedes the SvnCcHelpersScript/RevTree plugin:
- it does not rely on any Clearcase external scripts nor on any SVN custom properties to build the graph
- it does not use the GraphvizPlugin nor the Graphviz (dot) tool to render the graph. It is a pure Python implementation
- it uses the Trac repository cache, which dramatically speeds up the generation of the graph
- it can be configured and extended to support custom repository organization
The older plugin code has been removed from the TracHacks.org repository.
Since version 0.6.0, the plugin is able to process the tags as label instead of regular branch. The documentation for this new feature is yet to be written, and this feature introduces compatiblity breaks for the Enhancers.
Since version 0.5.0, only Trac 0.11 is supported.
Previous releases are still available for download, but are no longer maintained.
- 15470 by rjollos on 2016-04-14 00:17:26
The attribute isn't supported in setuptools >= 10.
- 13844 by eblot on 2014-04-09 13:50:23
Creates a new directory for Revtree dedicated to Trac 1.1+ installations
- 13716 by eblot on 2014-03-03 08:59:13
Closes #7608. Remove seed initializer, keep random color generation in case a branch is not named (which should never happen)
userprefs.png (16.0 KB) - added by 10 years ago.
User preferences (filters)
changeset-tip.png (47.2 KB) - added by 10 years ago.
Changeset info tip
revtree.png (92.5 KB) - added by 10 years ago.
Revtree view (compact mode)
revtree-stresstest.png (214.8 KB) - added by 10 years ago.
Revtree stresstest (timeline mode, reduced to 40%)
changeset-tip.2.png (79 bytes) - added by 10 years ago.
(empty image, attachment deletion is not allowed)
revtree2.png (79 bytes) - added by 10 years ago.
(empty image, attachment deletion is not allowed)
MainMenuItem.png (12.8 KB) - added by 9 years ago.
Revtree as a main menu item
ContextualMenuItem.png (12.5 KB) - added by 9 years ago.
Revtree as a contextual menu item
compatmatrix.txt (5.9 KB) - added by 9 years ago.
Compatibility matrix RST source (RST renderer is unavailable for now)
revtree.2.png (173.1 KB) - added by 9 years ago.
Revtree sample image (v0.6.0), w/ Firefox 3.0.1
Download all attachments as: .zip