|
39
|
1 = Trac Links =
|
|
|
2 As you might have guessed, TracLinks are a very fundamental feature of Trac.
|
|
|
3
|
|
|
4 They allow hyperlinking between Trac entities (tickets, reports, changesets, Wiki
|
|
|
5 pages, milestones and source files) from anywhere WikiFormatting is used.
|
|
|
6
|
|
|
7 TracLinks are generally of the form '''type:id''' (where ''id'' represents the
|
|
|
8 number, name or path of the item) though some frequently used kinds of items
|
|
|
9 also have short-hand notations.
|
|
|
10
|
|
|
11 Some examples:
|
|
|
12 * Tickets: '''!#1''' or '''!ticket:1'''
|
|
|
13 * Reports: '''!{1}''' or '''!report:1'''
|
|
|
14 * Changesets: '''!r1''', '''![1]''' or '''!changeset:1'''
|
|
|
15 * Revision log: '''!r1:3''', '''![1:3]''' or '''!log:#1:3'''
|
|
|
16 * Wiki pages: '''CamelCase''' or '''!wiki:CamelCase'''
|
|
|
17 * Milestones: '''!milestone:1.0'''
|
|
|
18 * Attachment: '''!attachment:ticket:944:attachment.1073.diff'''
|
|
|
19 * Files: '''!source:trunk/COPYING'''
|
|
|
20 * A specific file revision: '''!source:/trunk/COPYING#200'''
|
|
|
21 Display:
|
|
|
22 * Tickets: #1 or ticket:1
|
|
|
23 * Reports: {1} or report:1
|
|
|
24 * Changesets: r1, [1] or changeset:1
|
|
|
25 * Differences: r1:3, [1:3] or log:#1:3
|
|
|
26 * Wiki pages: CamelCase or wiki:CamelCase
|
|
|
27 * Milestones: milestone:1.0
|
|
|
28 * Files: source:trunk/COPYING
|
|
|
29 * Attachment: attachment:ticket:944:attachment.1073.diff
|
|
|
30 * A specific file revision: source:/trunk/COPYING#200
|
|
|
31
|
|
|
32 '''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to
|
|
|
33 pages whose names do not follow WikiPageNames rules, i.e., single words,
|
|
|
34 non-alphabetic characters, etc.
|
|
|
35
|
|
|
36 Trac links using the full (non-shorthand) notation can also be given a custom
|
|
|
37 link title like this:
|
|
|
38
|
|
|
39 {{{
|
|
|
40 [ticket:1 This is a link to ticket number one].
|
|
|
41 }}}
|
|
|
42
|
|
|
43 Display: [ticket:1 This is a link to ticket number one].
|
|
|
44
|
|
|
45 If the title is be omitted, only the id (the part after the colon) is displayed:
|
|
|
46
|
|
|
47 {{{
|
|
|
48 [ticket:1]
|
|
|
49 }}}
|
|
|
50
|
|
|
51 Display: [ticket:1]
|
|
|
52
|
|
|
53 It might seem a simple enough concept at a glance, but actually allows quite a complex network of information. In practice, it's very intuitive and simple to use, and we've found the "link trail" extremely helpful to better understand what's happening in a project or why a particular change was made.
|
|
|
54
|
|
|
55 == attachement: links ==
|
|
|
56
|
|
|
57 The link syntax for attachments is as follows:
|
|
|
58 * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current object
|
|
|
59 * !attachment:wiki:MyPage:the_file.txt creates a link to the attachment the_file.txt of the !MyPage wiki page
|
|
|
60 * !attachment:ticket:753:the_file.txt creates a link to the attachment the_file.txt of the ticket 753 !attachment:wiki:MyPage:the_file.txt
|
|
|
61
|
|
|
62 == source: links ==
|
|
|
63
|
|
|
64 The default behavior for a source:/some/path link is to open the directory browser
|
|
|
65 if the path points to a directory and otherwise open the log view.
|
|
|
66 It's also possible to link directly to a specific revision of a file like this: source:/some/file@123
|
|
|
67 or like this to link to the latest revision: source:/some/file@latest.
|
|
|
68 If the revision is specified, one can even link to a specific line number: !source:/some/file@123#L10
|
|
|
69 [[comment(TODO: remove the ! when Edgewall Trac is upgraded with the support for the line syntax)]]
|
|
|
70
|
|
|
71 == Quoting space in TracLinks ==
|
|
|
72
|
|
|
73 The usual syntax for quoting space is:
|
|
|
74
|
|
|
75 * !attachment:'the file.txt' or
|
|
|
76 * !attachment:"the file.txt"
|
|
|
77
|
|
|
78 == Where to use TracLinks ==
|
|
|
79 You can use TracLinks in:
|
|
|
80
|
|
|
81 * Source code (Subversion) commit messages
|
|
|
82 * Wiki pages
|
|
|
83 * Full descriptions for tickets, reports and milestones
|
|
|
84
|
|
|
85 and any other text fields explicitly marked as supporting WikiFormatting.
|
|
|
86
|
|
|
87 == Escaping Links ==
|
|
|
88
|
|
|
89 To prevent parsing of a !TracLink, you can escape it by preceding it with a '!' (exclamation mark).
|
|
|
90 {{{
|
|
|
91 !NoLinkHere.
|
|
|
92 ![42] is not a link either.
|
|
|
93 }}}
|
|
|
94
|
|
|
95 Display:
|
|
|
96 !NoLinkHere.
|
|
|
97 ![42] is not a link either.
|
|
|
98
|
|
|
99 ----
|
|
|
100 See also: WikiFormatting, TracWiki
|
|
|
101 |
