1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-dug-bugtracker">
\r
4 <title>Integration with Bug Tracking Systems / Issue Trackers</title>
\r
6 <primary>bug tracking</primary>
\r
9 <primary>bug tracker</primary>
\r
12 <primary>issue tracker</primary>
\r
15 <primary>bugtracker</primary>
\r
18 It is very common in Software Development for changes to be related to a specific
\r
19 bug or issue ID. Users of bug tracking systems (issue trackers) would like to associate
\r
20 the changes they make in Git with a specific ID in their issue tracker.
\r
21 Most issue trackers therefore provide a pre-commit hook script which parses the log
\r
22 message to find the bug ID with which the commit is associated.
\r
23 This is somewhat error prone since it relies on the user to write the log message
\r
24 properly so that the pre-commit hook script can parse it correctly.
\r
27 TortoiseGit can help the user in two ways:
\r
31 When the user enters a log message, a well defined line including
\r
32 the issue number associated with the commit can be added automatically.
\r
33 This reduces the risk that the user enters the issue number in a way
\r
34 the bug tracking tools can't parse correctly.
\r
37 Or TortoiseGit can highlight the part of
\r
38 the entered log message which is recognized by the issue tracker.
\r
39 That way the user knows that the log message can be parsed correctly.
\r
44 When the user browses the log messages, TortoiseGit
\r
45 creates a link out of each bug ID in the log message which fires
\r
46 up the browser to the issue mentioned.
\r
51 <sect2 id="tsvn-dug-bugtracker-link">
\r
52 <title>Adding Issue Numbers to Log Messages</title>
\r
54 You can integrate a bug tracking tool of your choice in
\r
55 TortoiseGit. To do this, you have to define
\r
56 some properties, which start with <literal>bugtraq:</literal>.
\r
57 They must be set on Folders: (<xref linkend="tsvn-dug-propertypage"/>)
\r
60 There are two ways to integrate TortoiseGit with issue trackers. One is
\r
61 based on simple strings, the other is based on
\r
62 <emphasis>regular expressions</emphasis>.
\r
63 The properties used by both approaches are:
\r
66 <term condition="pot">bugtraq:url</term>
\r
69 Set this property to the URL of your bug tracking tool.
\r
70 It must be properly URI encoded and it has to contain
\r
71 <literal>%BUGID%</literal>.
\r
72 <literal>%BUGID%</literal> is replaced with the Issue number
\r
73 you entered. This allows TortoiseGit
\r
74 to display a link in the log dialog, so when you are looking
\r
75 at the revision log you can jump directly to your
\r
77 You do not have to provide this property, but then
\r
78 TortoiseGit shows only the
\r
79 issue number and not the link to it.
\r
80 e.g the TortoiseGit project is using
\r
81 <systemitem class="url">http://issues.TortoiseGit.net/?do=details&id=%BUGID%</systemitem>
\r
84 You can also use relative URLs instead of absolute ones. This is
\r
85 useful when your issue tracker is on the same domain/server
\r
86 as your source repository. In case the domain name ever changes,
\r
87 you don't have to adjust the <literal>bugtraq:url</literal> property.
\r
88 There are two ways to specify a relative URL:
\r
91 If it begins with the string <literal>^/</literal> it is assumed
\r
92 to be relative to the repository root.
\r
93 For example, <literal>^/../?do=details&id=%BUGID%</literal>
\r
95 <systemitem class="url">http://TortoiseGit.net/?do=details&id=%BUGID%</systemitem>
\r
96 if your repository is located on
\r
97 <systemitem class="url">http://TortoiseGit.net/svn/trunk/</systemitem>.
\r
100 A URL beginning with the string <literal>/</literal> is assumed
\r
101 to be relative to the server's hostname.
\r
102 For example <literal>/?do=details&id=%BUGID%</literal>
\r
104 <systemitem class="url">http://TortoiseGit.net/?do=details&id=%BUGID%</systemitem>
\r
105 if your repository is located anywhere on
\r
106 <systemitem class="url">http://TortoiseGit.net</systemitem>.
\r
111 <term condition="pot">bugtraq:warnifnoissue</term>
\r
114 Set this to <literal>true</literal>, if you want
\r
115 TortoiseGit to warn you
\r
116 because of an empty issue-number text field. Valid values
\r
117 are <literal>true/false</literal>.
\r
119 If not defined, <literal>false</literal> is assumed.
\r
126 <sect3 id="tsvn-dug-bugtracker-link-simple">
\r
127 <title>Issue Number in Text Box</title>
\r
129 In the simple approach, TortoiseGit shows the user a separate
\r
130 input field where a bug ID can be entered. Then a separate line
\r
131 is appended/prepended to the log message the user entered.
\r
134 <term condition="pot">bugtraq:message</term>
\r
137 This property activates the bug tracking system
\r
138 in <emphasis>Input field</emphasis> mode.
\r
139 If this property is set, then TortoiseGit
\r
140 will prompt you to enter an issue number when you commit
\r
141 your changes. It's used to add a line at the end of the
\r
142 log message. It must contain
\r
143 <literal>%BUGID%</literal>, which is replaced with the
\r
144 issue number on commit. This ensures that your commit log
\r
145 contains a reference to the issue number which is always
\r
146 in a consistent format and can be parsed by your
\r
147 bug tracking tool to associate the issue number with a
\r
148 particular commit. As an example you might use
\r
149 <literal>Issue : %BUGID%</literal>,
\r
150 but this depends on your Tool.
\r
155 <term condition="pot">bugtraq:append</term>
\r
158 This property defines if the bug-ID is appended (true)
\r
159 to the end of the log message or inserted (false) at the
\r
160 start of the log message. Valid values are
\r
161 <literal>true/false</literal>.
\r
163 If not defined, <literal>true</literal> is assumed,
\r
164 so that existing projects don't break.
\r
170 <term condition="pot">bugtraq:label</term>
\r
173 This text is shown by TortoiseGit
\r
174 on the commit dialog to label the edit box where you enter
\r
175 the issue number. If it's not set,
\r
176 <literal>Bug-ID / Issue-Nr:</literal> will be displayed.
\r
177 Keep in mind though that the window will not be resized
\r
178 to fit this label, so keep the size of the label below
\r
184 <term condition="pot">bugtraq:number</term>
\r
187 If set to <literal>true</literal> only numbers are allowed
\r
188 in the issue-number text field.
\r
189 An exception is the comma, so you can comma separate several
\r
190 numbers. Valid values are <literal>true/false</literal>.
\r
192 If not defined, <literal>true</literal> is assumed.
\r
200 <sect3 id="tsvn-dug-bugtracker-link-regex">
\r
201 <title>Issue Numbers Using Regular Expressions</title>
\r
203 In the approach with <emphasis>regular expressions</emphasis>, TortoiseGit
\r
204 doesn't show a separate input field but marks the part of the log message
\r
205 the user enters which is recognized by the issue tracker. This is done while
\r
206 the user writes the log message. This also means that the bug ID can be
\r
207 anywhere inside a log message! This method is much more flexible, and is
\r
208 the one used by the TortoiseGit project itself.
\r
211 <term condition="pot">bugtraq:logregex</term>
\r
214 This property activates the bug tracking system
\r
215 in <emphasis>Regex</emphasis> mode.
\r
216 It contains either a single regular expressions,
\r
217 or two regular expressions separated by a newline.
\r
220 If two expressions are set, then the first expression is used as
\r
221 a pre-filter to find expressions which contain bug IDs. The
\r
222 second expression then extracts the bare bug IDs from the
\r
223 result of the first regex. This allows you to use a list
\r
224 of bug IDs and natural language expressions if you wish.
\r
225 e.g. you might fix several bugs and include a string something
\r
227 <quote>This change resolves issues #23, #24 and #25</quote>
\r
230 If you want to catch bug IDs as used in the expression above
\r
231 inside a log message, you could use the following regex strings,
\r
232 which are the ones used by the TortoiseGit project:
\r
233 <literal>[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+</literal> and
\r
234 <literal>(\d+)</literal>
\r
237 The first expression picks out <quote>issues #23, #24 and #25</quote>
\r
238 from the surrounding log message.
\r
239 The second regex extracts plain decimal numbers from the output
\r
240 of the first regex, so it will return <quote>23</quote>, <quote>24</quote>
\r
241 and <quote>25</quote> to use as bug IDs.
\r
244 Breaking the first regex down a little, it must start with
\r
245 the word <quote>issue</quote>, possibly capitalised.
\r
246 This is optionally followed by an <quote>s</quote> (more than one
\r
247 issue) and optionally a colon. This is followed by one or more
\r
248 groups each having zero or more leading whitespace, an optional
\r
249 comma or <quote>and</quote> and more optional space. Finally there
\r
250 is a mandatory <quote>#</quote> and a mandatory decimal number.
\r
253 If only one expression is set, then the bare bug IDs must be
\r
254 matched in the groups of the regex string. Example:
\r
255 <literal>[Ii]ssue(?:s)? #?(\d+)</literal>
\r
256 This method is required by a few issue trackers, e.g. trac,
\r
257 but it is harder to construct the regex. We recommend that you
\r
258 only use this method if your issue tracker documentation
\r
262 If you are unfamiliar with regular expressions, take a look at
\r
263 the introduction at
\r
264 <ulink url="http://en.wikipedia.org/wiki/Regular_expression">
\r
265 <citetitle>http://en.wikipedia.org/wiki/Regular_expression</citetitle>
\r
267 and the online documentation and tutorial at
\r
268 <ulink url="http://www.regular-expressions.info/">
\r
269 <citetitle>http://www.regular-expressions.info/</citetitle>
\r
278 If both the <literal>bugtraq:message</literal> and <literal>bugtraq:logregex</literal>
\r
279 properties are set, <literal>logregex</literal> takes precedence.
\r
283 Even if you don't have an issue tracker with a pre-commit hook parsing your
\r
284 log messages, you still can use this to turn the issues mentioned in your
\r
285 log messages into links!
\r
288 And even if you don't need the links, the issue numbers show up as a
\r
289 separate column in the log dialog, making it easier to find the changes
\r
290 which relate to a particular issue.
\r
294 Some <literal>tsvn:</literal> properties require a
\r
295 <literal>true/false</literal> value. TortoiseGit also understands
\r
296 <literal>yes</literal> as a synonym for <literal>true</literal> and
\r
297 <literal>no</literal> as a synonym for <literal>false</literal>.
\r
300 <title>Set the Properties on Folders</title>
\r
302 These properties must be set on folders for the system to work.
\r
303 When you commit a file or folder the properties are read from that folder.
\r
304 If the properties are not found there, TortoiseGit will search upwards
\r
305 through the folder tree to find them until it comes to an unversioned
\r
306 folder, or the tree root (eg. <literal>C:\</literal>) is found.
\r
307 If you can be sure that each user checks out only from e.g
\r
308 <filename>trunk/</filename> and not some sub-folder, then it's enough if
\r
309 you set the properties on <filename>trunk/</filename>.
\r
310 If you can't be sure, you should set the properties recursively
\r
311 on each sub-folder.
\r
312 A property setting deeper in the project hierarchy overrides settings on
\r
313 higher levels (closer to <filename>trunk/</filename>).
\r
316 For <literal>tsvn:</literal> properties <emphasis>only</emphasis>
\r
317 you can use the <guilabel>Recursive</guilabel> checkbox to set
\r
318 the property to all sub-folders in the hierarchy, without also
\r
319 setting it on all files.
\r
323 <title>No Issue Tracker Information from Repository Browser</title>
\r
325 Because the issue tracker integration depends upon accessing Git
\r
326 properties, you will only see the results when using a checked
\r
327 out working copy. Fetching properties remotely is a slow operation,
\r
328 so you will not see this feature in action from the repo browser.
\r
332 This issue tracker integration is not restricted to TortoiseGit; it can be used
\r
333 with any Git client. For more information, read the full
\r
334 <ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/doc/issuetrackers.txt">
\r
335 <citetitle>Issue Tracker Integration Specification</citetitle>
\r
337 in the TortoiseGit source repository.
\r
338 (<xref linkend="tsvn-preface-source"/> explains how to access the repository).
\r
341 <sect2 id="tsvn-dug-bugtracker-ref">
\r
342 <title>Getting Information from the Issue Tracker</title>
\r
344 The previous section deals with adding issue information to the
\r
345 log messages. But what if you need to get information from the issue
\r
346 tracker? The commit dialog has a Windows COM interface which allows
\r
347 integration an external program that can talk to your tracker.
\r
348 Typically you might want to query the tracker to get a list of
\r
349 open issues assigned to you, so that you can pick the issues that
\r
350 are being addressed in this commit.
\r
353 Any such interface is of course highly specific to your system,
\r
354 so we cannot provide this part, and describing how to create such a
\r
355 program is beyond the scope of this manual. The interface definition
\r
356 and sample programs can be obtained from the <literal>contrib</literal>
\r
358 <ulink url="http://TortoiseGit.tigris.org/svn/TortoiseGit/trunk/contrib/issue-tracker-plugins">
\r
359 <citetitle>TortoiseGit repository</citetitle>
\r
361 (<xref linkend="tsvn-preface-source"/> explains how to access the repository).
\r
364 For illustration purposes, let's suppose that your system administrator
\r
365 has provided you with an issue tracker plugin which you have installed,
\r
366 and that you have set up some of your working copies to use the plugin
\r
367 in TortoiseGit's settings dialog.
\r
368 When you open the commit dialog from a working copy to which the plugin
\r
369 has been assigned, you will see a new button at the top of the dialog.
\r
370 <figure id="tsvn-dug-bugtracker-dia-1">
\r
371 <title>Example issue tracker query dialog</title>
\r
372 <graphic fileref="../images/IssueTrackerQuery.png"/>
\r
374 In this example you can select one or more open issues. The plugin
\r
375 can then generate specially formatted text which it adds to your log
\r
379 If you work with the Google Code repository, you can use the ready-made
\r
380 <ulink url="http://code.google.com/p/gurtle/">
\r
381 <citetitle>Gurtle</citetitle>
\r
OSDN Git Service
