Last modified 2 years ago
macrolist
[[Image]]
Embed an image in wiki-formatted text.
The first argument is the file specification. The file specification may reference attachments in three ways:
- module:id:file, where module can be either wiki or ticket, to refer to the attachment named file of the specified wiki page or ticket.
- id:file: same as above, but id is either a ticket shorthand or a Wiki page name.
- file to refer to a local attachment named 'file'. This only works from within that wiki page or a ticket.
Also, the file specification may refer to repository files, using the source:file syntax (source:file@rev works also).
Files can also be accessed with a direct URLs; /file for a project-relative, //file for a server-relative, or http://server/file for absolute location of the file.
The remaining arguments are optional and allow configuring the attributes and style of the rendered <img> element:
- digits and unit are interpreted as the size (ex. 120, 25%) for the image
- right, left, center, top, bottom and middle are interpreted as the alignment for the image (alternatively, the first three can be specified using align=... and the last three using valign=...)
- link=some TracLinks... replaces the link to the image source by the one specified using a TracLinks. If no value is specified, the link is simply removed.
- nolink means without link to image source (deprecated, use link=)
- key=value style are interpreted as HTML attributes or CSS style
indications for the image. Valid keys are:
- align, valign, border, width, height, alt, title, longdesc, class, margin, margin-(left,right,top,bottom), id and usemap
- border, margin, and margin-* can only be a single number
- margin is superseded by center which uses auto margins
Examples:
[[Image(photo.jpg)]] # simplest
[[Image(photo.jpg, 120px)]] # with image width size
[[Image(photo.jpg, right)]] # aligned by keyword
[[Image(photo.jpg, nolink)]] # without link to source
[[Image(photo.jpg, align=right)]] # aligned by attribute
You can use image from other page, other ticket or other module.
[[Image(OtherPage:foo.bmp)]] # if current module is wiki
[[Image(base/sub:bar.bmp)]] # from hierarchical wiki page
[[Image(#3:baz.bmp)]] # if in a ticket, point to #3
[[Image(ticket:36:boo.jpg)]]
[[Image(source:/images/bee.jpg)]] # straight from the repository!
[[Image(htdocs:foo/bar.png)]] # image file in project htdocs dir.
Adapted from the Image.py macro created by Shun-ichi Goto <gotoh@…>
[[InterTrac]]
Provide a list of known InterTrac prefixes.
[[InterWiki]]
Provide a description list for the known InterWiki prefixes.
[[KnownMimeTypes]]
List all known mime-types which can be used as WikiProcessors.
Can be given an optional argument which is interpreted as mime-type filter.
[[MacroList]]
Display a list of all installed Wiki macros, including documentation if available.
Optionally, the name of a specific macro can be provided as an argument. In that case, only the documentation for that macro will be rendered.
Note that this macro will not be able to display the documentation of macros if the PythonOptimize option is enabled for mod_python!
[[PageOutline]]
Display a structural outline of the current wiki page, each item in the outline being a link to the corresponding heading.
This macro accepts four optional parameters:
- The first is a number or range that allows configuring the minimum and maximum level of headings that should be included in the outline. For example, specifying "1" here will result in only the top-level headings being included in the outline. Specifying "2-3" will make the outline include all headings of level 2 and 3, as a nested list. The default is to include all heading levels.
- The second parameter can be used to specify a custom title (the default is no title).
- The third parameter selects the style of the outline. This can be either inline or pullout (the latter being the default). The inline style renders the outline as normal part of the content, while pullout causes the outline to be rendered in a box that is by default floated to the right side of the other content.
- The fourth parameter specifies whether the outline is numbered or not. It can be either numbered or unnumbered (the former being the default). This parameter only has an effect in inline style.
[[RecentChanges]]
List all pages that have recently been modified, grouping them by the day they were last modified.
This macro accepts two parameters. The first is a prefix string: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are listed.
The second parameter is a number for limiting the number of pages returned. For example, specifying a limit of 5 will result in only the five most recently changed pages to be included in the list.
[[RepositoryIndex]]
Display the list of available repositories.
Can be given the following named arguments:
- format
-
Select the rendering format:
- compact produces a comma-separated list of repository prefix names (default)
- list produces a description list of repository prefix names
- table produces a table view, similar to the one visible in the Browse View page
- glob
- Do a glob-style filtering on the repository names (defaults to '*')
- order
- Order repositories by the given column (one of "name", "date" or "author")
- desc
- When set to 1, order by descending order
(since 0.12)
[[TicketQuery]]
Wiki macro listing tickets that match certain criteria.
This macro accepts a comma-separated list of keyed parameters, in the form "key=value".
If the key is the name of a field, the value must use the syntax of a filter specifier as defined in TracQuery#QueryLanguage. Note that this is not the same as the simplified URL syntax used for query: links starting with a ? character. Commas (,) can be included in field values by escaping them with a backslash (\).
Groups of field constraints to be OR-ed together can be separated by a litteral or argument.
In addition to filters, several other named parameters can be used to control how the results are presented. All of them are optional.
The format parameter determines how the list of tickets is presented:
- list -- the default presentation is to list the ticket ID next to the summary, with each ticket on a separate line.
- compact -- the tickets are presented as a comma-separated list of ticket IDs.
- count -- only the count of matching tickets is displayed
- table -- a view similar to the custom query view (but without the controls)
The max parameter can be used to limit the number of tickets shown (defaults to 0, i.e. no maximum).
The order parameter sets the field used for ordering tickets (defaults to id).
The desc parameter indicates whether the order of the tickets should be reversed (defaults to false).
The group parameter sets the field used for grouping tickets (defaults to not being set).
The groupdesc parameter indicates whether the natural display order of the groups should be reversed (defaults to false).
The verbose parameter can be set to a true value in order to get the description for the listed tickets. For table format only. deprecated in favor of the rows parameter
The rows parameter can be used to specify which field(s) should be viewed as a row, e.g. rows=description|summary
For compatibility with Trac 0.10, if there's a last positional parameter given to the macro, it will be used to specify the format. Also, using "&" as a field separator still works (except for order) but is deprecated.
[[TitleIndex]]
Insert an alphabetic list of all wiki pages into the output.
Accepts a prefix string as parameter: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are listed. If the prefix is specified, a second argument of value hideprefix can be given as well, in order to remove that prefix from the output.
Alternate format and depth named parameters can be specified:
- format=compact: The pages are displayed as comma-separated links.
- format=group: The list of pages will be structured in groups according to common prefix. This format also supports a min=n argument, where n is the minimal number of pages for a group.
- format=hierarchy: The list of pages will be structured according to the page name path hierarchy. This format also supports a min=n argument, where higher n flatten the display hierarchy
- depth=n: limit the depth of the pages to list. If set to 0, only toplevel pages will be shown, if set to 1, only immediate children pages will be shown, etc. If not set, or set to -1, all pages in the hierarchy will be shown.
- include=page1:page*2: include only pages that match an item in the colon-separated list of pages. If the list is empty, or if no include argument is given, include all pages.
- exclude=page1:page*2: exclude pages that match an item in the colon- separated list of pages.
The include and exclude lists accept shell-style patterns.
[[TracAdminHelp]]
Display help for trac-admin commands.
Examples:
[[TracAdminHelp]] # all commands [[TracAdminHelp(wiki)]] # all wiki commands [[TracAdminHelp(wiki export)]] # the "wiki export" command [[TracAdminHelp(upgrade)]] # the upgrade command
[[TracGuideToc]]
Display a table of content for the Trac guide.
This macro shows a quick and dirty way to make a table-of-contents for the Help/Guide?. The table of contents will contain the Trac* and WikiFormatting pages, and can't be customized. Search for TocMacro? for a a more customizable table of contents.
[[TracIni]]
Produce documentation for the Trac configuration file.
Typically, this will be used in the TracIni page. Optional arguments are a configuration section filter, and a configuration option name filter: only the configuration options whose section and name start with the filters are output.
trac ini
[account-manager]
| account_changes_notify_addresses | List of email addresses that get notified of user changes, ie, new user, password change and delete user. | (no default) |
| allow_delete_account | Allow users to delete their own account. | True |
| authentication_url | URL of the HTTP authentication service | (no default) |
| force_passwd_change | Force the user to change password when it's reset. | True |
| generated_password_length | Length of the randomly-generated passwords created when resetting the password for an account. | 8 |
| hash_method | Default hash type of new/updated passwords | HtDigestHashMethod |
| htdigest_realm | Realm to select relevant htdigest file entries | (no default) |
| htpasswd_hash_type | Default hash type of new/updated passwords | crypt |
| login_attempt_max_count | Lock user account after specified number of login attempts. Value zero means no limit. | (no default) |
| notify_actions | Comma separated list of actions to notify of. Available actions 'new', 'change', 'delete'. | (no default) |
| password_file | Path to the users file; leave blank to locate the users file by reading svnserve.conf | (no default) |
| password_format | (no default) | |
| password_store | (no default) | |
| persistent_sessions | Allow the user to be remembered across sessions without needing to re-authenticate. This is, user checks a "Remember Me" checkbox and, next time he visits the site, he'll be remembered. | false |
| reset_password | Set to false if there is no email system setup. | True |
| user_lock_max_time | Limit user account lock time to specified time (seconds). This is relevant only with user_lock_time_progression > 1. | 86400 |
| user_lock_time | Drop user account lock after specified time (seconds). Value zero means unlimited lock time. | 0 |
| user_lock_time_progression | Extend user account lock time incrementally. This is based on logarithmic calculation and decimal numbers accepted: Value '1' means constant lock time per failed login attempt. Value '2' means double locktime after 2nd lock activation, four times the initial locktime after 3rd, and so on. | 1 |
| username_char_blacklist | Always exclude some special characters from usernames. This is enforced upon new user registration. | :[] |
| verify_email | Verify the email address of Trac users. | True |
[attachment]
| max_size | Maximum allowed file size (in bytes) for ticket and wiki attachments. | 262144 |
| max_zip_size | Maximum allowed total size (in bytes) for an attachment list to be downloadable as a .zip. Set this to -1 to disable download as .zip. (since 0.13) | 2097152 |
| render_unsafe_content | Whether attachments should be rendered in the browser, or only made downloadable. Pretty much any file may be interpreted as HTML by the browser, which allows a malicious user to attach a file containing cross-site scripting attacks. For public sites where anonymous users can create attachments it is recommended to leave this option disabled (which is the default). | false |
[browser]
| color_scale | Enable colorization of the age column. This uses the same color scale as the source code annotation: blue is older, red is newer. (since 0.11) | True |
| downloadable_paths | List of repository paths that can be downloaded. Leave the option empty if you want to disable all downloads, otherwise set it to a comma-separated list of authorized paths (those paths are glob patterns, i.e. "*" can be used as a wild card) (since 0.10) | /trunk, /branches/*, /tags/* |
| hide_properties | Comma-separated list of version control properties to hide from the repository browser. (since 0.9) | svk:merge |
| intermediate_color | (r,g,b) color triple to use for the color corresponding to the intermediate color, if two linear interpolations are used for the color scale (see intermediate_point). If not set, the intermediate color between oldest_color and newest_color will be used. (since 0.11) | (no default) |
| intermediate_point | If set to a value between 0 and 1 (exclusive), this will be the point chosen to set the intermediate_color for interpolating the color value. (since 0.11) | (no default) |
| newest_color | (r,g,b) color triple to use for the color corresponding to the newest color, for the color scale used in blame or the browser age column if color_scale is enabled. (since 0.11) | (255, 136, 136) |
| oldest_color | (r,g,b) color triple to use for the color corresponding to the oldest color, for the color scale used in blame or the browser age column if color_scale is enabled. (since 0.11) | (136, 136, 255) |
| oneliner_properties | Comma-separated list of version control properties to render as oneliner wiki content in the repository browser. (since 0.11) | trac:summary |
| render_unsafe_content | Whether raw files should be rendered in the browser, or only made downloadable. Pretty much any file may be interpreted as HTML by the browser, which allows a malicious user to create a file containing cross-site scripting attacks. For open repositories where anyone can check-in a file, it is recommended to leave this option disabled (which is the default). | false |
| wiki_properties | Comma-separated list of version control properties to render as wiki content in the repository browser. (since 0.11) | trac:description |
[changeset]
| max_diff_bytes | Maximum total size in bytes of the modified files (their old size plus their new size) for which the changeset view will attempt to show the diffs inlined (since 0.10). | 10000000 |
| max_diff_files | Maximum number of modified files for which the changeset view will attempt to show the diffs inlined (since 0.10). | (no default) |
| wiki_format_messages | Whether wiki formatting should be applied to changeset messages. If this option is disabled, changeset messages will be rendered as pre-formatted text. | true |
[components]
This section is used to enable or disable components provided by plugins, as well as by Trac itself. The component to enable/disable is specified via the name of the option. Whether its enabled is determined by the option value; setting the value to enabled or on will enable the component, any other value (typically disabled or off) will disable the component.
The option name is either the fully qualified name of the components or the module/package prefix of the component. The former enables/disables a specific component, while the latter enables/disables any component in the specified package/module.
Consider the following configuration snippet:
[components] trac.ticket.report.ReportModule = disabled webadmin.* = enabled
The first option tells Trac to disable the report module. The second option instructs Trac to enable all components in the webadmin package. Note that the trailing wildcard is required for module/package matching.
To view the list of active components, go to the Plugins page on About Trac (requires CONFIG_VIEW permissions).
See also: TracPlugins
[header_logo]
| alt | Alternative text for the header logo. | (please configure the [header_logo] section in trac.ini) |
| height | Height of the header logo image in pixels. | -1 |
| link | URL to link to, from the header logo. | (no default) |
| src | URL of the image to use as header logo. It can be absolute, server relative or relative. If relative, it is relative to one of the /chrome locations: site/your-logo.png if your-logo.png is located in the htdocs folder within your TracEnvironment; common/your-logo.png if your-logo.png is located in the folder mapped to the htdocs_location URL. Only specifying your-logo.png is equivalent to the latter. | site/your_project_logo.png |
| width | Width of the header logo image in pixels. | -1 |
[inherit]
| htdocs_dir | Path to the shared htdocs directory. Static resources in that directory are mapped to /chrome/shared under the environment URL, in addition to common and site locations. This can be useful in site.html for common interface customization of multiple Trac environments. (since 0.13) | (no default) |
| plugins_dir | Path to the shared plugins directory. Plugins in that directory are loaded in addition to those in the directory of the environment plugins, with this one taking precedence. (since 0.11) | (no default) |
| templates_dir | Path to the shared templates directory. Templates in that directory are loaded in addition to those in the environments templates directory, but the latter take precedence. (since 0.11) | (no default) |
[intertrac]
This section configures InterTrac prefixes. Options in this section whose name contain a "." define aspects of the InterTrac prefix corresponding to the option name up to the ".". Options whose name don't contain a "." define an alias.
The .url is mandatory and is used for locating the other Trac. This can be a relative URL in case that Trac environment is located on the same server.
The .title information is used for providing a useful tooltip when moving the cursor over an InterTrac link.
The .compat option can be used to activate or disable a compatibility mode:
- If the targeted Trac is running a version below 0.10 ( r3526 to be precise), then it doesn't know how to dispatch an InterTrac link, and it's up to the local Trac to prepare the correct link. Not all links will work that way, but the most common do. This is called the compatibility mode, and is true by default.
- If you know that the remote Trac knows how to dispatch InterTrac links, you can explicitly disable this compatibility mode and then any TracLinks can become InterTrac links.
Example configuration:
[intertrac] # -- Example of setting up an alias: t = trac # -- Link to an external Trac: trac.title = Edgewall's Trac for Trac trac.url = http://trac.edgewall.org
[interwiki]
Every option in the [interwiki] section defines one InterWiki prefix. The option name defines the prefix. The option value defines the URL, optionally followed by a description separated from the URL by whitespace. Parametric URLs are supported as well.
Example:
[interwiki] MeatBall = http://www.usemod.com/cgi-bin/mb.pl? PEP = http://www.python.org/peps/pep-$1.html Python Enhancement Proposal $1 tsvn = tsvn: Interact with TortoiseSvn
[logging]
| log_file | If log_type is file, this should be a path to the log-file. Relative paths are resolved relative to the log directory of the environment. | trac.log |
| log_format | Custom logging format. If nothing is set, the following will be used: Trac[$(module)s] $(levelname)s: $(message)s In addition to regular key names supported by the Python logger library (see http://docs.python.org/library/logging.html), one could use: - $(path)s the path for the current environment - $(basename)s the last path component of the current environment - $(project)s the project name Note the usage of $(...)s instead of %(...)s as the latter form would be interpreted by the ConfigParser? itself. Example: ($(thread)d) Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s (since 0.10.5) | (no default) |
| log_level | Level of verbosity in log. Should be one of (CRITICAL, ERROR, WARN, INFO, DEBUG). | DEBUG |
| log_type | Logging facility to use. Should be one of (none, file, stderr, syslog, winlog). | none |
[milestone]
| stats_provider | Name of the component implementing ITicketGroupStatsProvider, which is used to collect statistics on groups of tickets for display in the milestone views. | DefaultTicketGroupStatsProvider |
[milestone-groups]
As the workflow for tickets is now configurable, there can be many ticket states, and simply displaying closed tickets vs. all the others is maybe not appropriate in all cases. This section enables one to easily create groups of states that will be shown in different colors in the milestone progress bar.
Example configuration (the default only has closed and active):
closed = closed # sequence number in the progress bar closed.order = 0 # optional extra param for the query (two additional columns: created and modified and sort on created) closed.query_args = group=resolution,order=time,col=id,col=summary,col=owner,col=type,col=priority,col=component,col=severity,col=time,col=changetime # indicates groups that count for overall completion percentage closed.overall_completion = true new = new new.order = 1 new.css_class = new new.label = new # one catch-all group is allowed active = * active.order = 2 # CSS class for this interval active.css_class = open # Displayed label for this group active.label = in progress
The definition consists in a comma-separated list of accepted status. Also, '*' means any status and could be used to associate all remaining states to one catch-all group.
The CSS class can be one of: new (yellow), open (no color) or closed (green). New styles can easily be added using the following selector: table.progress td.<class>
(since 0.11)
[mimeviewer]
| max_preview_size | Maximum file size for HTML preview. (since 0.9) | 262144 |
| mime_map | List of additional MIME types and keyword mappings. Mappings are comma-separated, and for each MIME type, there's a colon (":") separated list of associated keywords or file extensions. (since 0.10) | text/x-dylan:dylan, text/x-idl:ice, text/x-ada:ads:adb |
| pygments_default_style | The default style to use for Pygments syntax highlighting. | trac |
| pygments_modes | List of additional MIME types known by Pygments. For each, a tuple mimetype:mode:quality has to be specified, where mimetype is the MIME type, mode is the corresponding Pygments mode to be used for the conversion and quality is the quality ratio associated to this conversion. That can also be used to override the default quality ratio used by the Pygments render. | (no default) |
| tab_width | Displayed tab width in file preview. (since 0.9) | 8 |
| treat_as_binary | Comma-separated list of MIME types that should be treated as binary data. (since 0.11.5) | application/octet-stream, application/pdf, application/postscript, application/msword,application/rtf, |
[notification]
| admit_domains | Comma-separated list of domains that should be considered as valid for email addresses (such as localdomain). | (no default) |
| always_notify_owner | Always send notifications to the ticket owner (since 0.9). | false |
| always_notify_reporter | Always send notifications to any address in the reporter field. | false |
| always_notify_updater | Always send notifications to the person who causes the ticket property change and to any previous updater of that ticket. | true |
| ambiguous_char_width | Which width of ambiguous characters (e.g. 'single' or 'double') should be used in the table of notification mail. If 'single', the same width as characters in US-ASCII. This is expected by most users. If 'double', twice the width of US-ASCII characters. This is expected by CJK users. (since 0.12.2) | single |
| email_sender | Name of the component implementing IEmailSender. This component is used by the notification system to send emails. Trac currently provides SmtpEmailSender for connecting to an SMTP server, and SendmailEmailSender for running a sendmail-compatible executable. (since 0.12) | SmtpEmailSender |
| ignore_domains | Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains). | (no default) |
| mime_encoding | Specifies the MIME encoding scheme for emails. Valid options are 'base64' for Base64 encoding, 'qp' for Quoted-Printable, and 'none' for no encoding, in which case mails will be sent as 7bit if the content is all ASCII, or 8bit otherwise. (since 0.10) | none |
| sendmail_path | Path to the sendmail executable. The sendmail program must accept the -i and -f options. (since 0.12) | sendmail |
| smtp_always_bcc | Email address(es) to always send notifications to, addresses do not appear publicly (Bcc:). (since 0.10) | (no default) |
| smtp_always_cc | Email address(es) to always send notifications to, addresses can be seen by all recipients (Cc:). | (no default) |
| smtp_default_domain | Default host/domain to append to address that do not specify one. | (no default) |
| smtp_enabled | Enable email notification. | false |
| smtp_from | Sender address to use in notification emails. | trac@localhost |
| smtp_from_author | Use the action author as the sender of notification emails. (since 0.13) | false |
| smtp_from_name | Sender name to use in notification emails. | (no default) |
| smtp_password | Password for SMTP server. (since 0.9) | (no default) |
| smtp_port | SMTP server port to use for email notification. | 25 |
| smtp_replyto | Reply-To address to use in notification emails. | trac@localhost |
| smtp_server | SMTP server hostname to use for email notifications. | localhost |
| smtp_subject_prefix | Text to prepend to subject line of notification emails. If the setting is not defined, then the [$project_name] prefix. If no prefix is desired, then specifying an empty option will disable it. (since 0.10.1) | __default__ |
| smtp_user | Username for SMTP server. (since 0.9) | (no default) |
| ticket_subject_template | A Genshi text template snippet used to get the notification subject. By default, the subject template is $prefix #$ticket.id: $summary. $prefix being the value of the smtp_subject_prefix option. (since 0.11) | $prefix #$ticket.id: $summary |
| use_public_cc | Recipients can see email addresses of other CC'ed recipients. If this option is disabled (the default), recipients are put on BCC. (since 0.10) | false |
| use_short_addr | Permit email address without a host/domain (i.e. username only). The SMTP server should accept those addresses, and either append a FQDN or use local delivery. (since 0.10) | false |
| use_tls | Use SSL/TLS to send notifications over SMTP. (since 0.10) | false |
[project]
| admin | E-Mail address of the project's administrator. | (no default) |
| admin_trac_url | Base URL of a Trac instance where errors in this Trac should be reported. This can be an absolute or relative URL, or '.' to reference this Trac instance. An empty value will disable the reporting buttons. (since 0.11.3) | . |
| descr | Short description of the project. | My example project |
| footer | Page footer text (right-aligned). | Visit the Trac open source project at<br /><a href="http://trac.edgewall.org/">http://trac.edgewall.org/</a> |
| icon | URL of the icon of the project. | common/trac.ico |
| name | Name of the project. | My Project |
| url | URL of the main project web site, usually the website in which the base_url resides. This is used in notification e-mails. | (no default) |
[query]
| default_anonymous_query | The default query for anonymous users. The query is either in query language syntax, or a URL query string starting with ? as used in query: Trac links. (since 0.11.2) | status!=closed&cc~=$USER |
| default_query | The default query for authenticated users. The query is either in query language syntax, or a URL query string starting with ? as used in query: Trac links. (since 0.11.2) | status!=closed&owner=$USER |
| items_per_page | Number of tickets displayed per page in ticket queries, by default (since 0.11) | 100 |
| ticketlink_query | The base query to be used when linkifying values of ticket fields. The query is a URL query string starting with ? as used in query: Trac links. (since 0.12) | ?status=!closed |
[report]
| items_per_page | Number of tickets displayed per page in ticket reports, by default (since 0.11) | 100 |
| items_per_page_rss | Number of tickets displayed in the rss feeds for reports (since 0.11) | (no default) |
[repositories]
One of the alternatives for registering new repositories is to populate the [repositories] section of the trac.ini.
This is especially suited for setting up convenience aliases, short-lived repositories, or during the initial phases of an installation.
See TracRepositoryAdmin? for details about the format adopted for this section and the rest of that page for the other alternatives.
(since 0.12)
[revisionlog]
| default_log_limit | Default value for the limit argument in the TracRevisionLog. (since 0.11) | 100 |
| graph_colors | Comma-separated list of colors to use for the TracRevisionLog graph display. (since 0.13) | #cc0#0c0#0cc#00c#c0c#c00 |
[roadmap]
| stats_provider | Name of the component implementing ITicketGroupStatsProvider, which is used to collect statistics on groups of tickets for display in the roadmap views. | DefaultTicketGroupStatsProvider |
[search]
| default_disabled_filters | Specifies which search filters should be disabled by default on the search page. This will also restrict the filters for the quick search function. The filter names defined by default components are: wiki, ticket, milestone and changeset. For plugins, look for their implementation of the ISearchSource interface, in the get_search_filters() method, the first member of returned tuple. Once disabled, search filters can still be manually enabled by the user on the search page. (since 0.12) | (no default) |
| min_query_length | Minimum length of query string allowed when performing a search. | 3 |
[sqlite]
| extensions | Paths to sqlite extensions, relative to Trac environment's directory or absolute. (since 0.12) | (no default) |
[svn]
| branches | Comma separated list of paths categorized as branches. If a path ends with '*', then all the directory entries found below that path will be included. Example: /trunk, /branches/*, /projectAlpha/trunk, /sandbox/* | trunk, branches/* |
| tags | Comma separated list of paths categorized as tags. If a path ends with '*', then all the directory entries found below that path will be included. Example: /tags/*, /projectAlpha/tags/A-1.0, /projectAlpha/tags/A-v1.1 | tags/* |
[svn:externals]
The TracBrowser for Subversion can interpret the svn:externals property of folders. By default, it only turns the URLs into links as Trac can't browse remote repositories.
However, if you have another Trac instance (or an other repository browser like ViewVC) configured to browse the target repository, then you can instruct Trac which other repository browser to use for which external URL. This mapping is done in the [svn:externals] section of the TracIni.
Example:
[svn:externals] 1 = svn://server/repos1 http://trac/proj1/browser/$path?rev=$rev 2 = svn://server/repos2 http://trac/proj2/browser/$path?rev=$rev 3 = http://theirserver.org/svn/eng-soft http://ourserver/viewvc/svn/$path/?pathrev=25914 4 = svn://anotherserver.com/tools_repository http://ourserver/tracs/tools/browser/$path?rev=$rev
With the above, the svn://anotherserver.com/tools_repository/tags/1.1/tools external will be mapped to http://ourserver/tracs/tools/browser/tags/1.1/tools?rev= (and rev will be set to the appropriate revision number if the external additionally specifies a revision, see the SVN Book on externals for more details).
Note that the number used as a key in the above section is purely used as a place holder, as the URLs themselves can't be used as a key due to various limitations in the configuration file parser.
Finally, the relative URLs introduced in Subversion 1.5 are not yet supported.
(since 0.11)
[ticket]
| default_cc | Default cc: list for newly created tickets. | (no default) |
| default_component | Default component for newly created tickets. | (no default) |
| default_description | Default description for newly created tickets. | (no default) |
| default_keywords | Default keywords for newly created tickets. | (no default) |
| default_milestone | Default milestone for newly created tickets. | (no default) |
| default_owner | Default owner for newly created tickets. | (no default) |
| default_priority | Default priority for newly created tickets. | major |
| default_resolution | Default resolution for resolving (closing) tickets (since 0.11). | fixed |
| default_severity | Default severity for newly created tickets. | (no default) |
| default_summary | Default summary (title) for newly created tickets. | (no default) |
| default_type | Default type for newly created tickets (since 0.9). | defect |
| default_version | Default version for newly created tickets. | (no default) |
| max_comment_size | Don't accept tickets with a too big comment. (since 0.11.2) | 262144 |
| max_description_size | Don't accept tickets with a too big description. (since 0.11). | 262144 |
| preserve_newlines | Whether Wiki formatter should respect the new lines present in the Wiki text. If set to 'default', this is equivalent to 'yes' for new environments but keeps the old behavior for upgraded environments (i.e. 'no'). (since 0.11). | default |
| restrict_owner | Make the owner field of tickets use a drop-down menu. Be sure to understand the performance implications before activating this option. See Assign-to as Drop-Down List. Please note that e-mail addresses are not obfuscated in the resulting drop-down menu, so this option should not be used if e-mail addresses must remain protected. (since 0.9) | false |
| workflow | Ordered list of workflow controllers to use for ticket actions (since 0.11). | ConfigurableTicketWorkflow |
[ticket-custom]
In this section, you can define additional fields for tickets. See TracTicketsCustomFields for more details.
[ticket-workflow]
The workflow for tickets is controlled by plugins. By default, there's only a ConfigurableTicketWorkflow component in charge. That component allows the workflow to be configured via this section in the trac.ini file. See TracWorkflow for more details.
(since 0.11)
[timeline]
| abbreviated_messages | Whether wiki-formatted event messages should be truncated or not. This only affects the default rendering, and can be overriden by specific event providers, see their own documentation. (Since 0.11) | True |
| changeset_collapse_events | Whether consecutive changesets from the same author having exactly the same message should be presented as one event. That event will link to the range of changesets in the log view. (since 0.11) | false |
| changeset_long_messages | Whether wiki-formatted changeset messages should be multiline or not. If this option is not specified or is false and wiki_format_messages is set to true, changeset messages will be single line only, losing some formatting (bullet points, etc). | false |
| changeset_show_files | Number of files to show (-1 for unlimited, 0 to disable). This can also be location, for showing the common prefix for the changed files. (since 0.11). | 0 |
| default_daysback | Default number of days displayed in the Timeline, in days. (since 0.9.) | 30 |
| max_daysback | Maximum number of days (-1 for unlimited) displayable in the Timeline. (since 0.11) | 90 |
| newticket_formatter | Which formatter flavor (e.g. 'html' or 'oneliner') should be used when presenting the description for new tickets. If 'oneliner', the [timeline] abbreviated_messages option applies. (since 0.11). | oneliner |
| ticket_show_details | Enable the display of all ticket changes in the timeline, not only open / close operations (since 0.9). | false |
[trac]
| authz_file | The path to the Subversion authorization (authz) file. To enable authz permission checking, the AuthzSourcePolicy permission policy must be added to [trac] permission_policies. | (no default) |
| authz_module_name | The module prefix used in the authz_file for the default repository. If left empty, the global section is used. | (no default) |
| auto_preview_timeout | Inactivity timeout in seconds after which the automatic wiki preview triggers an update. This option can contain floating-point values. The lower the setting, the more requests will be made to the server. Set this to 0 to disable automatic preview. The default is 2.0 seconds. (since 0.12) | 2.0 |
| auto_reload | Automatically reload template files after modification. | false |
| backup_dir | Database backup location | db |
| base_url | Reference URL for the Trac deployment. This is the base URL that will be used when producing documents that will be used outside of the web browsing context, like for example when inserting URLs pointing to Trac resources in notification e-mails. | (no default) |
| database | Database connection string for this project | sqlite:db/trac.db |
| debug_sql | Show the SQL queries in the Trac log, at DEBUG level. (Since 0.11.5) | false |
| default_charset | Charset to be used when in doubt. | utf-8 |
| default_date_format | The date format. Valid option is 'iso8601' for ISO 8601 format, If not specified, use a browser's language. (since 0.13) | (no default) |
| default_handler | Name of the component that handles requests to the base URL. Options include TimelineModule, RoadmapModule, BrowserModule, QueryModule, ReportModule, TicketModule and WikiModule. The default is WikiModule. (since 0.9) | WikiModule |
| default_language | The preferred language to use if no user preference has been set. (since 0.12.1) | (no default) |
| default_timezone | The default timezone to use | (no default) |
| genshi_cache_size | The maximum number of templates that the template loader will cache in memory. The default value is 128. You may want to choose a higher value if your site uses a larger number of templates, and you have enough memory to spare, or you can reduce it if you are short on memory. | 128 |
| htdocs_location | Base URL for serving the core static resources below /chrome/common/. It can be left empty, and Trac will simply serve those resources itself. Advanced users can use this together with trac-admin ... deploy <deploydir> to allow serving the static resources for Trac directly from the web server. Note however that this only applies to the <deploydir>/htdocs/common directory, the other deployed resources (i.e. those from plugins) will not be made available this way and additional rewrite rules will be needed in the web server. | (no default) |
| mainnav | Order of the items to display in the mainnav navigation bar, listed by IDs. See also TracNavigation. | wiki, timeline, roadmap, browser, tickets, newticket, search |
| metanav | Order of the items to display in the metanav navigation bar, listed by IDs. See also TracNavigation. | login, logout, prefs, help, about |
| mysqldump_path | Location of mysqldump for MySQL database backups | mysqldump |
| never_obfuscate_mailto | Never obfuscate mailto: links explicitly written in the wiki, even if show_email_addresses is false or the user has not the EMAIL_VIEW permission (since 0.11.6). | false |
| permission_policies | List of components implementing IPermissionPolicy, in the order in which they will be applied. These components manage fine-grained access control to Trac resources. Defaults to the DefaultPermissionPolicy? (pre-0.11 behavior) and LegacyAttachmentPolicy? (map ATTACHMENT_* permissions to realm specific ones) | DefaultPermissionPolicy, LegacyAttachmentPolicy |
| permission_store | Name of the component implementing IPermissionStore, which is used for managing user and group permissions. | DefaultPermissionStore |
| pg_dump_path | Location of pg_dump for Postgres database backups | pg_dump |
| repository_dir | Path to the default repository. This can also be a relative path (since 0.11). This option is deprecated, and repositories should be defined in the repositories section, or using the "Repositories" admin panel. (since 0.12) | (no default) |
| repository_sync_per_request | List of repositories that should be synchronized on every page request. Leave this option empty if you have set up post-commit hooks calling trac-admin $ENV changeset added on all your repositories (recommended). Otherwise, set it to a comma-separated list of repository names. Note that this will negatively affect performance, and will prevent changeset listeners from receiving events from the repositories specified here. The default is to synchronize the default repository, for backward compatibility. (since 0.12) | (default) |
| repository_type | Default repository connector type. (since 0.10) This is also used as the default repository type for repositories defined in TracIni#repositories-section repositories or using the "Repositories" admin panel. (since 0.12) | svn |
| request_filters | Ordered list of filters to apply to all requests (since 0.10). | (no default) |
| resizable_textareas | Make <textarea> fields resizable. Requires JavaScript. (since 0.12) | true |
| secure_cookies | Restrict cookies to HTTPS connections. When true, set the secure flag on all cookies so that they are only sent to the server on HTTPS connections. Use this if your Trac instance is only accessible through HTTPS. (since 0.11.2) | false |
| show_email_addresses | Show email addresses instead of usernames. If false, we obfuscate email addresses. (since 0.11) | false |
| show_ip_addresses | Show IP addresses for resource edits (e.g. wiki). (since 0.11.3) | false |
| timeout | Timeout value for database connection, in seconds. Use '0' to specify no timeout. (Since 0.11) | 20 |
| use_base_url_for_redirect | Optionally use [trac] base_url for redirects. In some configurations, usually involving running Trac behind a HTTP proxy, Trac can't automatically reconstruct the URL that is used to access it. You may need to use this option to force Trac to use the base_url setting also for redirects. This introduces the obvious limitation that this environment will only be usable when accessible from that URL, as redirects are frequently used. (since 0.10.5) | false |
[versioncontrol]
| allowed_repository_dir_prefixes | Comma-separated list of allowed prefixes for repository directories when adding and editing repositories in the repository admin panel. If the list is empty, all repository directories are allowed. (since 0.12.1) | (no default) |
[wiki]
| ignore_missing_pages | Enable/disable highlighting CamelCase links to missing pages (since 0.9). | false |
| max_size | Maximum allowed wiki page size in bytes. (since 0.11.2) | 262144 |
| render_unsafe_content | Enable/disable the use of unsafe HTML tags such as <script> or <embed> with the HTML WikiProcessor (since 0.10.4). For public sites where anonymous users can edit the wiki it is recommended to leave this option disabled (which is the default). | false |
| safe_schemes | List of URI schemes considered "safe", that will be rendered as external links even if [wiki] render_unsafe_content is false. (since 0.11.8) | cvs, file, ftp, git, irc, http, https, news, sftp, smb, ssh, svn, svn+ssh |
| split_page_names | Enable/disable splitting the WikiPageNames with space characters (since 0.10). | false |
trac guide toc
Table of Contents
trac admin help
help
Show documentation
initenv [<projectname> <db> [<repostype> <repospath>]]
Create and initialize a new environment
If no arguments are given, then the required parameters are requested
interactively.
One or more optional arguments --inherit=PATH can be used to specify the
"[inherit] file" option at environment creation time, so that only the
options not already specified in one of the global configuration files are
written to the conf/trac.ini file of the newly created environment.
Relative paths are resolved relative to the "conf" directory of the new
environment.
attachment add <realm:id> <path> [author] [description]
Attach a file to a resource
The resource is identified by its realm and identifier. The attachment will
be named according to the base name of the file.
attachment export <realm:id> <name> [destination]
Export an attachment from a resource to a file or stdout
The resource is identified by its realm and identifier. If no destination
is specified, the attachment is output to stdout.
attachment list <realm:id>
List attachments of a resource
The resource is identified by its realm and identifier.
attachment remove <realm:id> <name>
Remove an attachment from a resource
The resource is identified by its realm and identifier.
changeset added <repos> <rev> [rev] [...]
Notify trac about changesets added to a repository
This command should be called from a post-commit hook. It will trigger a
cache update and notify components about the addition.
changeset modified <repos> <rev> [rev] [...]
Notify trac about changesets modified in a repository
This command should be called from a post-revprop hook after revision
properties like the commit message, author or date have been changed. It
will trigger a cache update for the given revisions and notify components
about the change.
component add <name> <owner>
Add a new component
component chown <name> <owner>
Change component ownership
component list
Show available components
component remove <name>
Remove/uninstall a component
component rename <name> <newname>
Rename a component
config get <section> <option>
Get the value of the given option in "trac.ini"
config remove <section> <option>
Remove the specified option from "trac.ini"
config set <section> <option> <value>
Set the value for the given option in "trac.ini"
deploy <directory>
Extract static resources from Trac and all plugins
hotcopy <backupdir> [--no-database]
Make a hot backup copy of an environment
The database is backed up to the 'db' directory of the destination, unless
the --no-database option is specified.
milestone add <name> [due]
Add milestone
milestone completed <name> <completed>
Set milestone complete date
The <completed> date must be specified in the "YYYY-MM-DD" format.
Alternatively, "now" can be used to set the completion date to the current
time. To remove the completion date from a milestone, specify an empty
string ("").
milestone due <name> <due>
Set milestone due date
The <due> date must be specified in the "YYYY-MM-DD" format. Alternatively,
"now" can be used to set the due date to the current time. To remove the
due date from a milestone, specify an empty string ("").
milestone list
Show milestones
milestone remove <name>
Remove milestone
milestone rename <name> <newname>
Rename milestone
permission add <user> <action> [action] [...]
Add a new permission rule
permission list [user]
List permission rules
permission remove <user> <action> [action] [...]
Remove a permission rule
priority add <value>
Add a priority value option
priority change <value> <newvalue>
Change a priority value
priority list
Show possible ticket priorities
priority order <value> up|down
Move a priority value up or down in the list
priority remove <value>
Remove a priority value
repository add <repos> <dir> [type]
Add a source repository
repository alias <name> <target>
Create an alias for a repository
repository list
List source repositories
repository remove <repos>
Remove a source repository
repository resync <repos> [rev]
Re-synchronize trac with repositories
When [rev] is specified, only that revision is synchronized. Otherwise, the
complete revision history is synchronized. Note that this operation can
take a long time to complete. If synchronization gets interrupted, it can
be resumed later using the `sync` command.
To synchronize all repositories, specify "*" as the repository.
repository set <repos> <key> <value>
Set an attribute of a repository
The following keys are supported: alias, description, dir, hidden, name,
type, url
repository sync <repos> [rev]
Resume synchronization of repositories
Similar to `resync`, but doesn't clear the already synchronized changesets.
Useful for resuming an interrupted `resync`.
To synchronize all repositories, specify "*" as the repository.
resolution add <value>
Add a resolution value option
resolution change <value> <newvalue>
Change a resolution value
resolution list
Show possible ticket resolutions
resolution order <value> up|down
Move a resolution value up or down in the list
resolution remove <value>
Remove a resolution value
session add <sid[:0|1]> [name] [email]
Create a session for the given sid
Populates the name and email attributes for the given session. Adding a
suffix ':0' to the sid makes the session unauthenticated, and a suffix ':1'
makes it authenticated (the default if no suffix is specified).
session delete <sid[:0|1]> [...]
Delete the session of the specified sid
An sid suffix ':0' operates on an unauthenticated session with the given
sid, and a suffix ':1' on an authenticated session (the default).
Specifying the sid 'anonymous' will delete all anonymous sessions.
session list [sid[:0|1]] [...]
List the name and email for the given sids
Specifying the sid 'anonymous' lists all unauthenticated sessions, and
'authenticated' all authenticated sessions. '*' lists all sessions, and is
the default if no sids are given.
An sid suffix ':0' operates on an unauthenticated session with the given
sid, and a suffix ':1' on an authenticated session (the default).
session purge <age>
Purge all anonymous sessions older than the given age
Age may be specified as a relative time like "90 days ago", or in YYYYMMDD
format.
session set <name|email> <sid[:0|1]> <value>
Set the name or email attribute of the given sid
An sid suffix ':0' operates on an unauthenticated session with the given
sid, and a suffix ':1' on an authenticated session (the default).
severity add <value>
Add a severity value option
severity change <value> <newvalue>
Change a severity value
severity list
Show possible ticket severities
severity order <value> up|down
Move a severity value up or down in the list
severity remove <value>
Remove a severity value
ticket remove <number>
Remove ticket
ticket_type add <value>
Add a ticket type
ticket_type change <value> <newvalue>
Change a ticket type
ticket_type list
Show possible ticket types
ticket_type order <value> up|down
Move a ticket type up or down in the list
ticket_type remove <value>
Remove a ticket type
upgrade
Upgrade database to current version
version add <name> [time]
Add version
version list
Show versions
version remove <name>
Remove version
version rename <name> <newname>
Rename version
version time <name> <time>
Set version date
The <time> must be specified in the "YYYY-MM-DD" format. Alternatively,
"now" can be used to set the version date to the current time. To remove
the date from a version, specify an empty string ("").
wiki dump <directory> [page] [...]
Export wiki pages to files named by title
Individual wiki page names can be specified after the directory. A name
ending with a * means that all wiki pages starting with that prefix should
be dumped. If no name is specified, all wiki pages are dumped.
wiki export <page> [file]
Export wiki page to file or stdout
wiki import <page> [file]
Import wiki page from file or stdin
wiki list
List wiki pages
wiki load <path> [...]
Import wiki pages from files
If a given path is a file, it is imported as a page with the name of the
file. If a path is a directory, all files in that directory are imported.
wiki remove <page>
Remove wiki page
wiki rename <page> <new_name>
Rename wiki page
wiki replace <path> [...]
Replace the content of wiki pages from files (DANGEROUS!)
This command replaces the content of the last version of one or more wiki
pages with new content. The previous content is lost, and no new entry is
created in the page history. The metadata of the page (time, author) is not
changed either.
If a given path is a file, it is imported as a page with the name of the
file. If a path is a directory, all files in that directory are imported.
WARNING: This operation results in the loss of the previous content and
cannot be undone. It may be advisable to backup the current content using
"wiki dump" beforehand.
wiki upgrade
Upgrade default wiki pages to current version
