Context Navigation

Trac FAQ

Here you can find answers to some of the most frequently asked questions about Trac. If you have a question not answered on this page, you can ask it on the MailingList or in the IrcChannel. See the TracSupport page for more options on getting support for Trac.

Management Summary
1. Where is the feature summary?
Installing and Running Trac
Trouble-shooting
Wiki
Timeline
1. How do I get Trac to resync the timeline with my subversion repository?
Browser
Tickets
Reports
1. Is there any way to remove reports?
Revision Log
1. How can I make the TracRevisionLog display the same information as the version control system after an edit to a repository revision property?
Notifications
1. How can I customize the email template?
Development
Miscellaneous

Management Summary

Where is the feature summary?

Where do I find the two-page summary on what Trac and its features are? I'm looking for some kind of documentation that I can show my manager, so that he'll get interested enough to allow me to spend the time and resources to test-install and evaluate further.

There's a WIP list on TracFeatures. Please help expand it.

Installing and Running Trac

What operating systems does Trac run on?

Trac will run on any system supported by Python and the depending modules. Today we are aware of people running Trac on various Linux distributions, Mac OS X, FreeBSD, NetBSD and MS Windows.

See also: TracOnFreeBsd , TracOnNetBsd , TracOnOsx, TracOnMandrakelinux, TracOnGentoo, TracOnDebian, TracOnFedoraCore, TracOnRedhat, TracOnWindows, TracOnSLES9 … and various others, listed in TracInstallPlatforms.

What license governs the use of Trac?

Starting with version 0.9, Trac is released under the modified BSD license. Versions of Trac prior to 0.9 were released under the GNU General Public License (GPL).

Can I migrate my bugs from Bugzilla?

There is a script to assist with the migration at source:trunk/contrib/bugzilla2trac.py For more information see: TracImport

How can I install Trac in a specific directory?

   ./setup.py install --prefix=/my/directory/for/trac

Can I replace SQLite with MySQL or PostgreSQL?

Yes, PostgreSQL since 0.9 and MySQL since 0.10.

See also: DatabaseBackend.

Can I manage multiple projects from a single installation of Trac?

(or do I have to setup a different directory for each one?)

Only one installation is required, then for each project create an Environment (using trac-admin <fooproj> initenv). They will be separate projects, all handled by the same installation of Trac.

Note: Right now there is no support for sharing information between projects.

The rationale for this is that the scope of Trac (1.0) is to manage a single project, and do it well. Support for larger multi-project management adds a lot of complexity, but is planned for post-1.0 development, probably as a separate framework around Trac.

See also: TracMultipleProjects

How can I create a nice URL to access trac.cgi?

If you are serving Trac with Apache, you can use the following directives to let your users access Trac with URLs like "http://www.example.com/trac/" rather than the default "http://www.example.com/cgi-bin/trac.cgi". This example shows how to set it up for Apache 2 on a Windows server, but it works just as well with Apache 1.3 or on Unix.

   # Map the Trac CGI into /trac/
   ScriptAliasMatch ^/trac(.*) "C:/Program Files/Apache Group/Apache2/cgi-bin/trac.cgi$1"

   # Tell Trac where its environment is stored
   <Location "/trac">
     SetEnv TRAC_ENV "C:/Subversion/trac/CogTool.db"
   </Location>

   # Authenticate the user
   <Location "/trac/login">
     AuthType Basic
     AuthName "Trac"
     AuthUserFile C:/Subversion/Repo/svn-users

     Require valid-user
   </Location>

   # Link the static files into /trac-static/
   # You'll need to change the trac.ini to point to /trac-static/ instead of /trac/
   Alias /trac-static/ "C:/Subversion/trac/htdocs/"

   # Allow access to the Trac static files
   <Directory "C:/Subversion/trac/htdocs">
     AllowOverride None
     Order allow,deny
     Allow from all
   </Directory>

Great software. Is there a guide on hacking the templates?

The templates are stored here

$PYTHON_HOME/share/trac

miscellaneous resources, including:

htdocs: images and CSS;
templates: Genshi templates; and

$TRAC_ENV/conf/trac.ini

settings, including (but not limited to):

templates_dir: where page templates are stored;
htdocs_location: the base URL for this Trac installation; and

See also: TracInterfaceCustomization#SiteAppearance

How do I reliably create backups of my Trac environment?

With the TracAdmin command hotcopy. See TracBackup for documentation.

Can I use Trac with a remote subversion repository?

You can't use Trac (not yet) with remote repository but you could mirror remote repository with subversion svnsync tool that is available since subversion 1.4.

If you're on Windows, the Python bindings support UNC paths, so you can use a repository that's shared out on another machine. Just use the UNC path instead of the local file path when setting up Trac. (Note that this can be slow and that this usage is not recommended by the Subversion development team.)

See also: #493, VersioningSystemBackend.

How do I change the format used for displaying date and time?

You change the format by setting an appropriate 'locale' in the configuration of your webserver. You do this for Apache by adding

  SetEnv LC_TIME "xx_YY"

Right after the line where you set TRAC_ENV.

If you're using mod_wsgi, it seems like SetEnv sets WSGI environment variable, so if the above does not work for you, you need to write instead:

  SetEnv trac.locale "xx_YY.UTF-8"

For Lighttpd you do this by adding the following to the bin-environment:

  "LC_TIME" => "xx_YY"

On a Linux/Un*x platform:

xx: The language code as defined in ISO 639
YY: The upper case, two letter country code as defined in ISO 3166

Examples: de_DE is Germany, en_GB is Great Britain and fr_FR is France For ending up with a ISO 8601 style, you could use en_DK or ro_RO.

On a Windows platform:

xx: The language name as defined in ISO 639
YY: The country name as defined in ISO 3166

Examples: German_Germany is Germany, English_United Kingdom is Great Britain and French_France is France

When it does not work

First, you should check, if the chosen locale is installed on the system at all.

On Linux, you can use

  localedef --list-archive

On FreeBSD you can use

  locale -a

to list the installed locale definitions.

If this is not the problem, then LC_TIME may be overridden by LC_ALL or LANGUAGE defined in the system environment. You may try one of them (LANGUAGE has highest priority) instead LC_TIME. Note that LC_TIME just affects the date and time display, whereas LC_ALL and LANGUAGE also affect handling of system messages, sorting and other country dependent output/input. So the conservative way is to stick to LC_TIME if possible. On RedHat change /etc/sysconfig/httpd and set

  HTTPD_LANG=xx_YY

On Debian, edit /etc/default/apache2 and add ENV="${ENV} LC_TIME=xx_YY". Run dpkg-reconfigure locales as root if the locale you require is not available.

Changing the date and time format with mod_python

To change the date and time format when using mod_python you should instead use 'PythonOption' to set the 'TracLocale'. So for a Un*x-like system, simply do this…

  <Location /projects>
    SetHandler mod_python
    PythonOption TracLocale "de_DE.UTF-8"
    ...
  </Location>

or on a Windows system:

  <Location /projects>
    SetHandler mod_python
    PythonOption TracLocale "English_United Kingdom"
   ...
  </Location>

Changing the date and time format with mod_wsgi

The WSGI file should resemble the following:

import sys 
sys.stdout = sys.stderr 
import os 

os.environ['TRAC_ENV_PARENT_DIR'] = '/path/to/trac' 
os.environ['PYTHON_EGG_CACHE'] = '/python/egg-cache' 

import trac.web.main 

def application(environ, start_request):
    environ['trac.locale'] = 'English_United Kingdom'
    return trac.web.main.dispatch_request(environ, start_request)

Replace 'English_United Kingdom' with the required locale and format depending on the operating system (see above).

I am getting svn import errors with trac, what's going on?

Make sure you install the Python bindings for Subversion, just having Subversion is not good enough. See TracSubversion which explains where you can find packages for this bindings or build them by yourself.

The error reported by Trac will look something like this:

  Indexing repository
  Failed to initialize environment. No module named svn
  Traceback (most recent call last):
  File "/usr/lib/python2.3/site-packages/trac/scripts/admin.py", line 616, in do_initenv repos = self.__env.get_repository()
  File "/usr/lib/python2.3/site-packages/trac/env.py", line 155, in get_repository from trac.versioncontrol.svn_fs import SubversionRepository
  File "/usr/lib/python2.3/site-packages/trac/versioncontrol/svn_fs.py", line 25, in ?  from svn import fs, repos, core, delta
  ImportError: No module named svn

Note that in recent versions of Trac, this error reads rather: TracError: Unsupported version control system "svn". .

To verify you should have a libsvn and svn directory underneath Python's site-packages directory, but see rather TracSubversion#unsupported-vcs for more detailed troubleshooting information.

If you do not have this use something like the following to fix this:

On Gentoo Linux:

  USE="python" emerge subversion

On FreeBSD use the ports/devel/subversion-python port (preferred way) or ports/devel/subversion with

  WITH_PYTHON=true

When using pkgsrc, please make sure to use the pkgsrc/devel/py-subversion pkg.

Why do my PHP pages show up blank in the Browser?

If you turn on full logging, you might see this error in your trac.log file:

WARNING: HTML preview using <trac.mimeview.php.PHPRenderer object at 0xb7b6032c> failed (You appear to be using the PHP CGI binary.  Trac requires the CLI version for syntax highlighting.)

Steps to fix:

Install PHP command-line interface (CLI) - (page with more details)
Configure TracIni to use the PHP CLI.
1. On Windows, something like this:
```
[mimeviewer]
php_path = c:\PHP\php.exe
```
2. On Linux, something like this:
```
[mimeviewer]
php_path = /usr/local/bin/php
```

Can I use Trac with a subtree of my subversion repository?

When setting up your Trac environment simply append the subtree of interest to the repository path, eg, if your repository resides in '/var/svn' and you only want to handle a project '/myproject' in Trac, you'd specify '/var/svn/myproject' as your repository path. Alternatively you can change the path in the 'repository_dir' setting in your 'conf/trac.ini' inside the trac instance directory.

Does Trac support svn:external subversion repositories?

Sort of, since version 0.11. See TracIni#svn:externals-section.

Is there a Web interface as an alternative to the `trac-admin` command-line tool?

Yes, users with TRAC_ADMIN permission will see an Admin tab on the main navigation. Users with other _ADMIN permissions (e.g. TICKET_ADMIN) will also see this tab, but only a subset of the functionality will be available. Note that not all the operations of trac-admin have an equivalent in the web interface. You still need the command-line tool for doing resync, hotcopy, etc.

Trac seems to run very slowly

Despite its name, the "Fast CGI" solution is often quite a bit slower than mod_python or mod_wsgi. Try the TracModPython or TracModWSGI installation. Changing from fcgi to mod_python/mod_wsgi can easily give an order of magnitude (n*10) increase in performance.

Trouble-shooting

I have issues with Subversion and Trac

Start by reading the TracSubversion page and its troubleshooting section.

In particular, there are detailed instructions for how to deal with very common installation issues, like the Unsupported version control system "svn" error or the RuntimeError: instance.__dict__ not accessible in restricted mode ones.

I have issues with SQLite/Pysqlite and Trac

Start by reading the PySqlite page and its troubleshooting section.

I have issues with Apache/ModPython and Trac

Start by reading the TracModPython page and its troubleshooting section.

I have issues with UTF-8 encoding/decoding

On occasion, you may bump into the following error:

UnicodeDecodeError: 'utf8' codec can't decode byte 0xXX in position i: unexpected code byte

This error usually shows up after one of the following events occurred:

you've imported an existing Trac database from an older Trac installation,
you've converted the database backend (from MySQL to SQLite, …),
you've used a faulty Trac plugin

See TracUnicode to find out how to convert a database archive.

I have issues with … Trac

… check the TracTroubleshooting page, which contains general advices about how to figure out what's really going on.

What about this "Authentication information not available." error?

Before trying to log in, an authentication mechanism (outside of Trac) has to be set-up. See:

Internet explorer will not upload (multiple) files when Trac is used over SSL (Apache server only)

Internet explorer is not too keen on obeying rules. Try to add this line in your httpd.conf:

SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0

See also: http://www.modssl.org/docs/2.7/ssl_faq.html#ToC48

After an upgrade: Browser directory listings are 'Access Denied'

It's possible you have two versions of trac active at the same time. See the comments on ticket #3915

After an upgrade: When I edit a wiki page there are no buttons to submit or preview changes

It's possible you have two versions of trac active at the same time. See the comments on ticket #3915

Wiki

What is a "Wiki"?

The term Wiki is a shortened form of WikiWikiWeb. A Wiki is a database of pages that can be collaboratively edited using a web browser.

Did you copy the previous question from the MoinMoin FAQ?

Why yes, thanks for asking.

How to add a new page to Wiki using the browser?

Just access the URL http://yourhost/trac/wiki/newpage and click on the "Edit This page link"

Good "wiki" style suggests however that you start by editing some existing page, then insert a WikiPageName and save the page. The WikiPageName link will be displayed as a missing link (i.e. LikeThat), and by following this link, you end up on the page creation interface. By following this practice, you tend to avoid OrphanedPages.

See also: WikiNewPage

How do I remove a page from the Wiki?

Users with the WIKI_DELETE permission can click the "Delete Page" button at the bottom of the page.

The TracAdmin utility can also remove Wiki pages like so:

    trac-admin <yourprojenv> wiki remove PageName

Does Trac support Unicode/UTF-8 or any other encodings?

Yes, Trac uses UTF-8 internally for all text. See TracUnicode for a detailed description.

How can I make links to files on the network via UNC path links?

Make a wiki link that looks like [file:///%5C%5Cserver/path/to/file/readme.txt Readme]. In Mozilla or Firefox type about:config in your browser window and change security.checkloaduri to false. More info: http://kb.mozillazine.org/Firefox_:_FAQs_:_About:config_Entries

How do I see all pages that link to the current page?

Currently you can use a 3rd party BackLinksMacro to do this

There is also ticket #611 requesting this feature in Trac.

Is there a way to remove an attached file from a page?

Users with WIKI_DELETE permissions can delete attachments. To do this, login as the privileged user, click on the attachment. The attachment page will now have a "Delete Attachment" button you can use to delete the attachment. Note that is an irreversible operation.

Is there a way to edit attachments?

Could I download attached file, update it and upload it back with same name? See related #948.

Can I convert MediaWiki pages to Trac?

You can use the attachment:wiki:TracWiki:mediawiki2trac.py script as a starting point. WikiProcessor for the MediaWiki styles has been started as trac plugin on http://trac-hacks.org/wiki/MediaWikiPluginMacro.

Can I directly add questions to this Wiki FAQ?

Yes, you can! However, please don't add unanswered questions, only topics that you've regularly answered yourself or issues you're familiar with. Good places to ask questions are the MailingList and the IrcChannel.

Just click Edit this page at the bottom of the page.

Please note that this page is no longer written using reStructuredText… Thanks to the [[PageOutline]] macro, the index for this FAQ is generated automatically.

But then how do we control spammers and malicious contributors?

I guess you would get an answer rapidly if you added a malicious contribution, and you just might get a bruise (and we'll send you an ICE).

Does Trac support individual section edits like MediaWiki and DokuWiki?

Not currently, but this issue (#1024) is a planned feature for the 0.13 release.
Meanwhile, you might try the SectionEditPlugin.

Timeline

How do I get Trac to resync the timeline with my subversion repository?

trac-admin in trac 0.8 and above has a built-in command to resync the repository that works like this.

  trac-admin <yourprojenv> repository resync <reponame>

Browser

On Windows, why does Trac not display diffs?

Note: this problem concerns old version of Subversion and Trac, and can probably be deleted from the FAQ. The tree diff functionality provided by the subversion python bindings use an external diff_ command. On UNIX-like systems, diff is usually installed already, so this wasn't an issue there. Installing diffutils should solve the problem.

After installing diffutils, you will need to add the path to the diff executable to the Windows PATH environment variable and reboot the machine.

Does Trac support syntax coloring/highlighting of source code files?

Yes, using several methods. See TracSyntaxColoring for details.

How do I disable wiki formatting of changeset messages?

You can configure this in your TracIni:

[changeset]
wiki_format_messages = false

Tickets

Is there any way to remove tickets?

Yes, using TracAdmin (in milestone:0.10 or later?):

  trac-admin <yourprojenv> ticket remove <num>

You have to go through the db file in order to remove a ticket. For a web interface, see TracHacks:TicketDeletePlugin.

How to get a drop-down user list for ticket owners?

You can replace the free text box with a drop-down list of known users to assign ticket owners: See TracTickets#Assign-toasDrop-DownList.

Is there any way to migrate tickets from one Trac installation to another?

For example, is it possible to import and export in the same way as one can using trac-admin for the wiki?

NOTE: For Trac 0.10 and above, you can use the Datamover plugin to do this.

NOTE: WushNet has created a utility script to copy tickets to a second instance of Trac. It handles renumbering of tickets, preservation of ticket history and custom fields, and the copying of attachments. It is currently tested on Trac 0.11.x and limited to Trac instances on the same server which use the SQLite backend. The script is available at http://wush.net/trac/foss/wiki/TracDataCp

A possible approach (until someone comes up with a better one?!) is to use the sqlite engine to export the tickets and changes, generate a script, and then insert the records into the second trac installation. E.g.:

  [root@xgbemf6002 root]# sqlite <path/to/trac_project/db/trac.db>
  SQLite version 2.8.15
  Enter ".help" for instructions

  sqlite> .output ticket.sql
  sqlite> .dump ticket

Outputs the table, both the schema and the data, into the file ticket.sql. You can then import this file into your new installation by doing something like sqlite < ticket.sql. You will need to either drop the ticket table in your new installation or remove the "create table" statement out of the ticket.sql file.

As provided below, the database schema can be found here

Moving from Win2k, SQLite 3 to Debian 3.1, SQLite 2 the following worked:

sqlite3.exe e:\\project\\db\\trac.db .dump > c:\\project.sql

copy this file and any attachments/templates to the new server.

sqlite /new/project/db/trac.db

.read project.sql

.exit

Move the other files into position. Done!

How can I associate usernames (e.g. for assigned tickets) with email addresses for notification?

In version 0.9 Trac will use the email address from the Settings page for authenticated users.

Can Trac automatically update a ticket when I commit a changeset?

Yes, you can setup Subversion to update the Trac ticket when you commit changes with a message listing tickets that are fixed or related.

Trac 0.12

Trac 0.12 introduced a new, more general, method to accomplish this. You can, for example, activate the optional CommitTicketUpdater plugin that is part of Trac 0.12. Then you also need to make Trac aware of commits in the source control system through hook scripts.

For more info about the optional (i.e. included but not enabled by default) CommitTicketUpdater plugin provided by Trac, see the file tracopt/ticket/commit_updater.py source:/trunk/tracopt/ticket/commit_updater.py .

For another example on how to relate tickets and changesets, see TracHacks:TracTicketChangesetsPlugin.

Trac 0.11 and previous versions

If you are using a stable version prior to Trac 0.12, you should instead get the script which matches your release - for example source:/branches/0.11-stable/contrib/trac-post-commit-hook (if you build from source, you will find the correct script version in your trac-xxx/contrib folder)

If the trac-post-commit-hook script does not appear to be working, for some extra clues try running it from the command-line using the account normally used to run it and without an environment (as it's normally executed). Change to the relevant user and execute the following from the subversion repository hooks directory:

env - ./post-commit /svn/test 7

This will also check your subversion hook is calling trac-post-commit-hook.

If the results give you something like this:

"ImportError: no module named trac.env"

then it's likely python has not been found properly by line 1 of trac-post-commit-hook, so change line 1 to suit your system, such as:

#!/usr/local/bin/python

If it runs manually but not from Subversion, make sure first line in script post-commit (for linux) is #!/bin/sh (does not show in example script).

We're already using Bugzilla, can I disable tickets?

Disable the ticket components, in your TracIni:

[components]
trac.ticket.* = disabled

Also, it's quite simple to write a plugin to redirect ticket references to your legacy ticket system: e.g. mantis_tickets.py (replacement for all bug links with disabled tickets) or mantis_tickets_link.py (parses "Mantis #xxxxxx" links only).

Microsoft Outlook displays ticket notification mails in a non-monospace font, how do I change that?

Outlook can be configured to use a monospace font by going to Tools → Options… → Email format → Fonts … → International Fonts. Highlight Unicode in the language list, select Courier New as the proportional font, and select Unicode (UTF-8) as encoding.

Or try http://outlooktrac.googlepages.com/ - utility to sync trac tickets with outlook.

Reports

Is there any way to remove reports?

Yes, if you have the proper permissions, you should be able to delete a report simply by viewing it and clicking Delete.

Revision Log

How can I make the TracRevisionLog display the same information as the version control system after an edit to a repository revision property?

The solution is the same as discussed here. The TracRevisionLog must be resynced with the repository after an edit to a revision property in the version control back-end. The trac-admin repository resync command can be used to resync the entire repository or a single revision. See trac-admin help or TracAdmin#FullCommandReference for more details.

One can even create a hook to automatically resync the revision history in Trac with that in the repository following a property edit.

In Subversion, make a copy of the post-revprop-change template, define TRACENV and TRACADMIN, and add the following to the hook script:

$TRACADMIN $TRACENV changeset modified <reponame> $REV

Notifications

How can I customize the email template?

Copy ticket_notify_email.txt to $TRAC_ENV/templates and modify the template as desired. For more details see TracNotification#Customizingthee-mailcontent.

Development

How can I contribute to the project?

There are several ways to contribute, including submitting patches, sending feedback and reporting bugs. For details, see HowToContribute. For development specific documentation, see TracDev.

Are there any provisions for I18N and L10N? Is it enough to translate the templates?

Yes and no. Merely translating the templates is not enough to provide complete internationalization of Trac. Python supports gettext just fine, but templates might require some extra work.

The standpoint of the TracTeam right now is to postpone translation efforts until the feature base and source code has stabilized somewhat, so as to not add too much extra work until 1.0.

That said, people have already started looking into it, and making some good suggestions already. We will need help with translation efforts. If you're interested in volunteering, please consider joining the mailing list.

For more information refer to TracL10N

Is the Database schema available anywhere?

See TracDev/DatabaseSchema.

In Trac 0.8.x and below the schema is available in source:branches/0.8-stable/trac/db_default.py

Trac no longer has the schema in plain SQL since it was necessary to abstract the table creation in order to support other database platforms. However, the structure in db_default.py still provides a representation of the schema.

To get a definitive schema for your install:

  prompt> sqlite3 /path/to/tracdata/yourinstance/db/trac.db
  sqlite> .schema

Miscellaneous

Is it possible to disable the version control component?

Some users prefer to use Trac as an issue-tracker and Wiki and thus don't require the version control subsystem. When initializing a project's environment with trac-admin, don't enter anything for the repository directory (i.e. keep the default). Then add the following to project/conf/trac.ini:

   [components]
   trac.versioncontrol.* = disabled

How do I create or change a milestone with an associated date?

Using trac-admin, specifically the milestone time or milestone add command. The input format for the date is rather limited still, and should be a string like this: 'Jun 3, 2003'. Note the string must be quoted for proper parsing. Example:

  trac-admin myprojenv milestone add anniversary 'Jun 3, 2003'

Can I use Trac with other version control systems (CVS, Arch, etc.)?

Currently only Subversion is supported, but Trac will probably support other systems in the future. See discussion of this on VersioningSystemBackend.

There are a number of plugins for different version control systems on trac-hacks.

Also, CVSTrac is a similar, but far simpler system which can track a CVS repository

Can I use LDAP to manage user accounts?

Apache supports LDAP authentication with mod_auth_ldap. You can use this in place of the other authenticate methods used in the installation guides. It may be easier, however, depending on your installation, to use mod_auth_pam with Apache and configure PAM to use LDAP for authentication.

You can use LDAP to manage your Trac groups and permissions with the TracHacks:LdapPlugin.

Download in other formats:

Plain Text