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 Git 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.
TortoiseGit 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 TortoiseGit 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, TortoiseGit 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
TortoiseGit. To do this, you have to define
some configuration, which start with bugtraq..
These settings can be edited using TortoiseGit settings dialog: Section 2.36.7.2, “Config”
There are two ways to integrate TortoiseGit with issue trackers. One is based on simple strings, the other is based on regular expressions. The configuration used by both approaches are:
- bugtraq.url
-
Set this configuration to the URL of your bug tracking tool. It must be properly URI encoded and it has to contain
%BUGID%.%BUGID%is replaced with the Issue number you entered. This allows TortoiseGit 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 configuration, but then TortoiseGit shows only the issue number and not the link to it. e.g the TortoiseGit project is usinghttps://tortoisegit.org/issue/%BUGID% - bugtraq.warnifnoissue
-
Set this to
true, if you want TortoiseGit to warn you because of an empty issue-number text field. Valid values aretrue/false. If not defined,falseis assumed.
In the simple approach, TortoiseGit 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.
- bugtraq.message
-
This configuration activates the bug tracking system in Input field mode. If this configuration is set, then TortoiseGit 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 useIssue : %BUGID%, but this depends on your Tool. - bugtraq.append
-
This configuration 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
true/false. If not defined,trueis assumed, so that existing projects don't break. - bugtraq.label
-
This text is shown by TortoiseGit 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 20-25 characters. - bugtraq.number
-
If set to
trueonly numbers are allowed in the issue-number text field. An exception is the comma, so you can comma separate several numbers. Valid values aretrue/false. If not defined,trueis assumed.
In the approach with regular expressions, TortoiseGit 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 TortoiseGit project itself.
- bugtraq.logregex
-
This configuration 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 TortoiseGit project:
[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+and(\d+)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:
[Ii]ssue(?:s)? #?(\d+)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 https://en.wikipedia.org/wiki/Regular_expression , and the online documentation and tutorial at http://www.regular-expressions.info/ .
If both the bugtraq:message and bugtraq:logregex
properties are set, logregex takes precedence.
![[Tip]](tip.png)
|
Tip |
|---|---|
|
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. |
This is a hierarchical git configuration to associate issue tracker plugin with your project,
rather than with to a specific directory path. Such settings are more portable.
To deploy the settings, set to Project level and commit .tgitconfig.
- bugtraq.provideruuid
-
This is the GUID of 32-bit issue tracker plugin.
- bugtraq.provideruuid64
-
This is the GUID of 64-bit issue tracker plugin.
- bugtraq.providerparams
-
This is the parameter string for the issue tracker plugin.
This issue tracker integration is not restricted to TortoiseGit; it can be used with other clients (e.g. TortoiseSVN). For more information, read the full Issue Tracker Integration Specification in the TortoiseGit source repository. (Section 3, “TortoiseGit is free!” 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 Windows 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 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 programs can be obtained from the contrib
folder in the
TortoiseGit repository
.
(Section 3, “TortoiseGit is free!” explains how to access the repository).
A summary of the API is also given in Appendix B, IBugTraqProvider interface
Another (working) example plugin in C# is
Gurtle
which implements the required COM interface to interact with the
Google Code
issue tracker.
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 trees to use the plugin in TortoiseGit's settings dialog. When you open the commit dialog from a working tree 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.