It is very common in Software Development for changes to be related to a specific bug or issue ID. Users of bug tracking systems (issue trackers) would like to associate the changes they make in Subversion with a specific ID in their issue tracker. Most issue trackers therefore provide a pre-commit hook script which parses the log message to find the bug ID with which the commit is associated. This is somewhat error prone since it relies on the user to write the log message properly so that the pre-commit hook script can parse it correctly.
TortoiseSVN can help the user in two ways:
When the user enters a log message, a well defined line including the issue number associated with the commit can be added automatically. This reduces the risk that the user enters the issue number in a way the bug tracking tools can't parse correctly.
Or TortoiseSVN can highlight the part of the entered log message which is recognized by the issue tracker. That way the user knows that the log message can be parsed correctly.
When the user browses the log messages, TortoiseSVN creates a link out of each bug ID in the log message which fires up the browser to the issue mentioned.
You can integrate a bug tracking tool of your choice in
TortoiseSVN. To do this, you have to define
some properties, which start with
They must be set on Folders: (the section called “Project Settings”)
When you edit any of the bugtraq properties a special property editor is used to make it easier to set appropriate values.
There are two ways to integrate TortoiseSVN with issue trackers. One is based on simple strings, the other is based on regular expressions. The properties used by both approaches are:
Set this property to the URL of your bug tracking tool.
It must be properly URI encoded and it has to contain
%BUGID% is replaced with the Issue number
you entered. This allows TortoiseSVN
to display a link in the log dialog, so when you are looking
at the revision log you can jump directly to your
bug tracking tool.
You do not have to provide this property, but then
TortoiseSVN shows only the
issue number and not the link to it.
e.g the TortoiseSVN project is using
You can also use relative URLs instead of absolute ones. This is
useful when your issue tracker is on the same domain/server
as your source repository. In case the domain name ever changes,
you don't have to adjust the
There are two ways to specify a relative URL:
If it begins with the string
^/ it is assumed
to be relative to the repository root.
will resolve to
if your repository is located on
A URL beginning with the string
/ is assumed
to be relative to the server's hostname.
will resolve to
if your repository is located anywhere on
Set this to
true, if you want
TortoiseSVN to warn you
because of an empty issue-number text field. Valid values
If not defined,
false is assumed.
In the simple approach, TortoiseSVN shows the user a separate input field where a bug ID can be entered. Then a separate line is appended/prepended to the log message the user entered.
This property activates the bug tracking system
in Input field mode.
If this property is set, then TortoiseSVN
will prompt you to enter an issue number when you commit
your changes. It's used to add a line at the end of the
log message. It must contain
%BUGID%, which is replaced with the
issue number on commit. This ensures that your commit log
contains a reference to the issue number which is always
in a consistent format and can be parsed by your
bug tracking tool to associate the issue number with a
particular commit. As an example you might use
Issue : %BUGID%,
but this depends on your Tool.
This text is shown by TortoiseSVN
on the commit dialog to label the edit box where you enter
the issue number. If it's not set,
Bug-ID / Issue-Nr: will be displayed.
Keep in mind though that the window will not be resized
to fit this label, so keep the size of the label below
If set to
true only numbers are allowed
in the issue-number text field.
An exception is the comma, so you can comma separate several
numbers. Valid values are
If not defined,
true is assumed.
This property defines if the bug-ID is appended (true)
to the end of the log message or inserted (false) at the
start of the log message. Valid values are
If not defined,
true is assumed,
so that existing projects don't break.
In the approach with regular expressions, TortoiseSVN doesn't show a separate input field but marks the part of the log message the user enters which is recognized by the issue tracker. This is done while the user writes the log message. This also means that the bug ID can be anywhere inside a log message! This method is much more flexible, and is the one used by the TortoiseSVN project itself.
This property activates the bug tracking system in Regex mode. It contains either a single regular expressions, or two regular expressions separated by a newline.
If two expressions are set, then the first expression is used as a pre-filter to find expressions which contain bug IDs. The second expression then extracts the bare bug IDs from the result of the first regex. This allows you to use a list of bug IDs and natural language expressions if you wish. e.g. you might fix several bugs and include a string something like this: “This change resolves issues #23, #24 and #25”.
If you want to catch bug IDs as used in the expression above
inside a log message, you could use the following regex strings,
which are the ones used by the TortoiseSVN project:
The first expression picks out “issues #23, #24 and #25” from the surrounding log message. The second regex extracts plain decimal numbers from the output of the first regex, so it will return “23”, “24” and “25” to use as bug IDs.
Breaking the first regex down a little, it must start with the word “issue”, possibly capitalised. This is optionally followed by an “s” (more than one issue) and optionally a colon. This is followed by one or more groups each having zero or more leading whitespace, an optional comma or “and” and more optional space. Finally there is a mandatory “#” and a mandatory decimal number.
If only one expression is set, then the bare bug IDs must be
matched in the groups of the regex string. Example:
This method is required by a few issue trackers, e.g. trac,
but it is harder to construct the regex. We recommend that you
only use this method if your issue tracker documentation
tells you to.
If you are unfamiliar with regular expressions, take a look at the introduction at http://en.wikipedia.org/wiki/Regular_expression , and the online documentation and tutorial at http://www.regular-expressions.info/ .
It's not always easy to get the regex right so to help out there is a test dialog built into the bugtraq properties dialog. Click on the button to the right of the edit boxes to bring it up. Here you can enter some test text, and change each regex to see the results. If the regex is invalid the edit box background changes to red.
If both the
properties are set,
logregex takes precedence.
Even if you don't have an issue tracker with a pre-commit hook parsing your log messages, you still can use this to turn the issues mentioned in your log messages into links!
And even if you don't need the links, the issue numbers show up as a separate column in the log dialog, making it easier to find the changes which relate to a particular issue.
tsvn: properties require a
true/false value. TortoiseSVN also understands
yes as a synonym for
no as a synonym for
These properties must be set on folders for the system to work.
When you commit a file or folder the properties are read from that folder.
If the properties are not found there, TortoiseSVN will search upwards
through the folder tree to find them until it comes to an unversioned
folder, or the tree root (e.g.
C:\) is found.
If you can be sure that each user checks out only from e.g
trunk/ and not some sub-folder, then it's enough if
you set the properties on
If you can't be sure, you should set the properties recursively
on each sub-folder.
A property setting deeper in the project hierarchy overrides settings on
higher levels (closer to
For project properties only,
you can use the Recursive checkbox to set
the property to all sub-folders in the hierarchy, without also
setting it on all files.
When you add new sub-folders to a working copy using TortoiseSVN, any project properties present in the parent folder will automatically be added to the new child folder too.
Because the issue tracker integration depends upon accessing Subversion properties, you will only see the results when using a checked out working copy. Fetching properties remotely is a slow operation, so you will not see this feature in action from the repo browser unless you started the repo browser from your working copy. If you started the repo browser by entering the URL of the repository you won't see this feature.
For the same reason, project properties will not be propagated automatically when a child folder is added using the repo browser.
This issue tracker integration is not restricted to TortoiseSVN; it can be used with any Subversion client. For more information, read the full Issue Tracker Integration Specification in the TortoiseSVN source repository. (the section called “License” explains how to access the repository.)
The previous section deals with adding issue information to the log messages. But what if you need to get information from the issue tracker? The commit dialog has a COM interface which allows integration an external program that can talk to your tracker. Typically you might want to query the tracker to get a list of open issues assigned to you, so that you can pick the issues that are being addressed in this commit.
Any such interface is of course highly specific to your issue tracker system,
so we cannot provide this part, and describing how to create such a
program is beyond the scope of this manual. The interface definition
and sample plugins in C# and C++/ATL can be obtained from the
folder in the
(the section called “License” explains how to access the repository.)
A summary of the API is also given in Chapter 6, IBugtraqProvider interface.
Another (working) example plugin in C# is
which implements the required COM interface to interact with the
For illustration purposes, let's suppose that your system administrator has provided you with an issue tracker plugin which you have installed, and that you have set up some of your working copies to use the plugin in TortoiseSVN's settings dialog. When you open the commit dialog from a working copy to which the plugin has been assigned, you will see a new button at the top of the dialog.
In this example you can select one or more open issues. The plugin can then generate specially formatted text which it adds to your log message.