Loading...

Table of Contents

  1. ticket: links
  2. attachment: links
  3. raw-attachment: links
  4. source: links
  5. export: links
  6. changeset: and log: links
  7. blog: links
  8. forum: topic: and message: links
  9. search: links
  10. help: links
  11. query: links
  12. timeline: links
  13. build: links
  14. Project-relative links
  15. InterWiki links
  16. Quoting space in TracLinks
  17. Argument and Anchor support in links
  18. Where to use links
  19. Escaping Links

Using Links

"Links" are a very fundamental feature of the system.

They allow hyperlinking between different entities (tickets, reports, changesets, wiki pages, milestones and source files) from anywhere WikiFormatting is used.

Links are generally of the form type:id (where id represents the number, name or path of the item) though some frequently used kinds of items also have short-hand notations.

Some examples:

  • Tickets: #1 or [ticket:1]
  • Ticket comments: [comment:2:ticket:1]
  • Reports: {1} or [report:1]
  • Changesets: [1] or [changeset:1]
  • Revision Logs (list several changesets): r1:3, [1:3] or [log:trunk/@1:3]
  • Diffs: diff:@1:3, diff:tags/version1//tags/version2 or diff:trunk@1//trunk@3
  • Wiki pages: CamelCase or [wiki:CamelCase]
  • Milestones: [milestone:1.0]
  • Attachment: attachment:myversion.diff:ticket:1
  • Files: [source:trunk/COPYING]

Display examples (only some shown, and example data):

Note: The [wiki:CamelCase] form is convenient to refer to pages whose names do not follow normal pagename rules, i.e., single words, non-alphabetic characters, etc.

Links using the full (non-shorthand) notation can also be given a custom link title like this: 

[ticket:1 This is a link to ticket number one].

Display (strikethrough if closed): This is a link to ticket number one.

If the title is be omitted, only the id (the part after the colon) is displayed: 

[ticket:1]

Display (strikethrough if closed): 1

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.

In addition to the ticket examples provided above, this link type also supports a list format to link to a custom query and tickets that also give you 'Previous' and 'Next' navigation when browsing them. Example using ticket shorthand notation: 

#12,23-34,35,36,50,40-42

The link syntax for attachments is as follows: 

[attachment:the_file.txt] -- Creates a link to the attachment the_file.txt of the current object.
[attachment:the_file.txt:wiki:MyPage] -- Creates a link to the attachment the_file.txt of the MyPage wiki page.
[attachment:the_file.txt:ticket:753] -- Creates a link to the attachment the_file.txt of the ticket 753.

The usual syntax for quoting space is: 

[attachment:'the file.txt'] or [attachment:"the file.txt"]

The regular attachment: links (above) provides a general web presentation of the attachment. It is also possible to link to the raw attachment by using raw-attachment:the_file.txt link syntax.

The default behavior for a source:/some/path link is to open the directory browser if the path points to a directory and otherwise open the log view.

It's also possible to link directly to a specific revision of a file like this:

  • source:/some/file@123 - link to the file's revision 123
  • source:/some/file@head - link explicitly to the latest revision of the file

If the revision is specified, one can even link to a specific line number:

  • source:/some/file@123#L10
  • source:/tag/0.10@head#L10

Finally, one can also highlight an arbitrary set of lines:

  • source:/some/file@123:10-20,100,103#L99 - highlight lines 10 to 20, and lines 100 and 103.

To force the download of a file in the repository, as opposed to displaying it in the browser, use the export link. Several forms are available:

  • export:/some/file - get the HEAD revision of the specified file
  • export:123:/some/file - get revision 123 of the specified file
  • export:/some/file@123 - get revision 123 of the specified file

To link to changesets and lists of changesets, many alternatives and shorthand forms can be used. Here are some examples:

  • [changeset:3 See the changeset for changes] - link to changeset 3 to display log message, files and diffs for the change, using a custom link message.
  • [3] - shorthand for [changeset:3].
  • [log:@33:44] - list changesets in a given range.
  • [34:44] -- Link to page listing changesets 34-44 allowing you to select the changeset to view in detail.
  • [log:/trunk] -- link to revision log for a given path.
  • [log:/trunk@34:44] -- Limits the listing to the changesets in the range affecting repository path /trunk.
  • [log:@33,34,37,42:44] - combine specific changsets with changeset ranges.
  • [33,34,37,42:44] - is a shorthand version of [log:@33,34,37,42:44].

Note that in all of the above, a revision range can be written indifferently x:y or x-y.

Items in the blog can be linked to in a simple manner:

  • [blog:some_post] - a link to a named blog post
  • [blog:author/simon] - link to the list of posts by author 'simon'
  • [blog:category/stuff] - link to the list of posts in category 'stuff'
  • [blog:2008/01] - link to posts in a given time period

Linking to various resources in the Forum can easily be achieved using these simple link types:

[forum:1]Link to forum list for Forum 1 (can list many topics).
[topic:3 Discuss this here!]Link to a specific topic/discussion thread (id=3).
[message:12]Link to a specific message in a discussion (id=12).

Every resource inside the Forum is marked clearly with an ID.

From the Wiki, it is possible to link to a specific search, using search: links: 

search:?q=bug will search for the string "crash"
search:?q=install+help&wiki=on will search for "trac" and "link" in wiki pages only

It is also possible to link directly to the help pages, or any specific help page either - either common help pages, or project specific help pages: 

[help:index] or [help:index Help] -- Will show the first help page.
[help:common] -- Will show the first common help page.
[help:site] -- Will show the first project help page.
[help:common/HelpUser/WikiFormatting] -- Link to a named page in the common section.

You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page. 

[query:status!=closed&version=0.8 Active tickets against 0.8]

Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading ? character: 

[query:?status=assigned&group=owner Assigned tickets by owner]

This uses a very simple query language to specify the criteria - see HelpUser/Query for more information on syntax and possibilities.

This implements a timeline: link resolver prefix. The argument must be a date string in the ​ISO:8601 format, with at least the year and the month specified. Example:

  • [timeline:2007-03-01]
  • [timeline:2007-03-01T13:00:00]

Links to a Continuous Integration build, with build ID as input:

  • build:23

Any other resource can also be linked using the project-relative link syntax which is just starting the link with '/'. Examples:

To link to another project on CodeResort, it is better to use the InterWiki syntax, but server-relative urls are supported as this example shows [//about/home Read more about the service].

See HelpUser/InterWiki for information about linking to other projects or external websites in a generic manner.

Immediately after a TracLinks prefix, targets containing space characters should be enclosed in a pair of quotes or double quotes. Examples:

  • wiki:"The whitespace convention"
  • attachment:'the file.txt' or
  • attachment:"the file.txt"
  • attachment:"ticket:123:the file.txt"

Most links support arguments and anchor references, allowing you to write links such as the following examples:

  • [/newticket?summary=Feedback]
  • [changeset:1#file3]

You can use links in:

  • Source code (Subversion) commit messages
  • Wiki pages
  • Full descriptions for tickets, reports and milestones

and any other text fields explicitly marked as supporting WikiFormatting.

To prevent parsing of a TracLink, you can escape it by preceding it with a '!' (exclamation mark). 

 !NoLinkHere. ![42] is not a link either.

Display:

NoLinkHere. [42] is not a link either.