Edgewall Software

Changes between Initial Version and Version 1 of TracLinks

Show
Ignore:
Timestamp:
06/03/06 08:37:54 (8 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracLinks

    v1 v1  
     1= Trac Links = 
     2As you might have guessed, TracLinks are a very fundamental feature of Trac. 
     3 
     4They allow hyperlinking between Trac entities (tickets, reports, changesets, Wiki 
     5pages, milestones and source files) from anywhere WikiFormatting is used. 
     6 
     7TracLinks are generally of the form '''type:id''' (where ''id'' represents the 
     8number, name or path of the item) though some frequently used kinds of items 
     9also have short-hand notations. 
     10 
     11Some 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''' 
     21Display: 
     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 
     33pages whose names do not follow WikiPageNames rules, i.e., single words, 
     34non-alphabetic characters, etc. 
     35 
     36Trac links using the full (non-shorthand) notation can also be given a custom 
     37link title like this: 
     38 
     39{{{ 
     40[ticket:1 This is a link to ticket number one]. 
     41}}} 
     42 
     43Display: [ticket:1 This is a link to ticket number one]. 
     44 
     45If the title is be omitted, only the id (the part after the colon) is displayed: 
     46 
     47{{{ 
     48[ticket:1] 
     49}}} 
     50 
     51Display: [ticket:1] 
     52 
     53It 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 
     57The 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 
     64The default behavior for a source:/some/path link is to open the directory browser  
     65if the path points to a directory and otherwise open the log view.  
     66It's also possible to link directly to a specific revision of a file like this: source:/some/file@123  
     67or like this to link to the latest revision: source:/some/file@latest. 
     68If 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 
     73The usual syntax for quoting space is: 
     74 
     75 * !attachment:'the file.txt' or 
     76 * !attachment:"the file.txt"  
     77 
     78== Where to use TracLinks == 
     79You can use TracLinks in: 
     80 
     81 * Source code (Subversion) commit messages 
     82 * Wiki pages 
     83 * Full descriptions for tickets, reports and milestones 
     84 
     85and any other text fields explicitly marked as supporting WikiFormatting. 
     86 
     87== Escaping Links == 
     88 
     89To 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 
     95Display: 
     96 !NoLinkHere. 
     97 ![42] is not a link either. 
     98 
     99---- 
     100See also: WikiFormatting, TracWiki 
     101