| 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 | |