# wiki

name: CamelCase
author: trac
text:
  = !CamelCase

  New wiki links are automatically created when concatenating capitalized words, such that for example the words 'Camel' and 'Case' concatenated form a link to this CamelCase page.

  !CamelCase is the original wiki convention for creating hyperlinks, with the additional requirement that the capital letters are followed by a lower-case letter; hence "AlabamA" and "ABc" will not be links.

  == Customizing the Wiki behavior

  While Trac remains faithful to the original Wiki style, it also provides a number of ways to accommodate users with different preferences:
   * To prevent the creation of a link for the CamelCase word, prefix the word with an exclamation mark (`!`): `!CamelCase`.
   * By default a CamelCase word with no corresponding Wiki page will be rendered as a gray link followed by a question mark. This is useful for example when the CamelCase style is used to name code artefacts like class names, and a Wiki page is expected to exist to document each class. The behavior can be configured through the [TracIni#wiki-ignore_missing_pages-option "[wiki] ignore_missing_pages"] option in TracIni.
   * To automatically insert space characters between the words of a CamelCase link when rendering the link, enable [TracIni#wiki-split_page_names-option "[wiki] split_page_names"] of TracIni.
   * Creation of explicit Wiki links is also easy, see WikiPageNames for details.
   * Wiki formatting can be disabled completely in some places, for example when rendering commit log messages. See the [TracIni#changeset-wiki_format_messages-option "[wiki] wiki_format_messages"] option in TracIni.

  See TracIni for more information on the available options.

  == More information on !CamelCase

   * http://c2.com/cgi/wiki?WikiCase
   * https://en.wikipedia.org/wiki/CamelCase

  ----
  See also: WikiPageNames, WikiNewPage, WikiFormatting, TracWiki


name: InterMapTxt
author: trac
text:
  = InterMapTxt

  == This is the place for defining InterWiki prefixes

  This page is interpreted in a special way by Trac, in order to support
  !InterWiki links in a flexible and dynamic way.
  It is modeled after the MeatBall:InterMapTxt page.
  In addition, an optional comment is allowed after the mapping.

  The [#PrefixDefinitions code block] after the first line separator in this page
  will be interpreted as a list of !InterWiki specifications:
  {{{
  prefix URL [# comment]
  }}}

  See InterWiki for more details of the URL syntax.

  New !InterWiki links can be created by editing this page and adding to the list.
  Note however that ''deletions'' are also taken into account immediately,
  so be aware that your changes might disable links in your wiki. It may be better to use comments for deprecating prefixes that are used in your wiki.

  The definitions below can be viewed in the [InterWiki#ListofActivePrefixes list of active prefixes].

  ----

  == Prefix Definitions

  {{{
  PEP     https://www.python.org/dev/peps/pep-$1/   # Python Enhancement Proposal
  PythonBug    https://bugs.python.org/issue$1      # Python Issue #$1
  Python-issue https://bugs.python.org/issue$1      # Python Issue #$1
  PythonWiki    https://wiki.python.org/moin/       # Python Wiki


  Trac-ML  http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/ # Message $1 in Trac Mailing List
  trac-dev http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/   # Message $1 in Trac Development Mailing List

  apidoc https://www.edgewall.org/docs/trac-trunk/html/$1.html # $1 in the API documentation for Trac
  apiref https://www.edgewall.org/docs/trac-trunk/epydoc/$1.html # $1 in the Epydoc API reference for Trac

  bitten   https://bitten.edgewall.org/intertrac/    # Bitten's Trac

  Mercurial https://www.mercurial-scm.org/wiki/              # the wiki for the Mercurial distributed SCM
  hg        https://www.mercurial-scm.org/repo/$1/rev/$2     # Changeset $1 $2 in Mercurial repository
  hg-issue  https://www.mercurial-scm.org/bts/issue          # Issue $1 in Mercurial BTS

  RFC       https://tools.ietf.org/html/rfc$1          # IETF's RFC $1
  ISO       https://en.wikipedia.org/wiki/ISO_         # ISO Standard $1 in Wikipedia
  kb        https://support.microsoft.com/kb/$1/en-us/ # Article $1 in Microsoft's Knowledge Base

  pypi        https://pypi.org/project/   # $1 package in the Python Package Index
  CheeseShop  https://pypi.org/project/   # $1 package in the Python Package Index
  peak        http://peak.telecommunity.com/DevCenter/     # $1 in Python Enterprise Application Kit's Wiki
  setuptools-issue https://bugs.python.org/setuptools/issue # issue$1 in legacy Setuptools tracker
  pypa-setuptools-issue https://bitbucket.org/pypa/setuptools/issue/ # issue #$1 in BitBucket Setuptools tracker

  SQLite      https://www.sqlite.org/cvstrac/wiki?p=$1     # $1 page in the CvsTrac for SQLite
  SQLiteTkt   https://www.sqlite.org/cvstrac/tktview?tn=$1 # Ticket $1 in the CvsTrac for SQLite

  mysql-bugs  https://bugs.mysql.com/bug.php?id=  # Bug #$1 in MySQL's bug database
  mysql-issue https://bugs.mysql.com/bug.php?id=  # Bug #$1 in MySQL's bug database

  MODPYTHON          https://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance
  mod-python-issue   https://issues.apache.org/jira/browse/MODPYTHON- # Issue $1 in mod_python's JIRA instance

  SvnWiki     https://www.orcaware.com/svn/wiki/                       # Subversion Wiki
  svnissue    http://subversion.tigris.org/issues/show_bug.cgi?id=     # Subversion issue #$1
  svn-issue   http://subversion.tigris.org/issues/show_bug.cgi?id=     # Subversion issue #$1
  svncset     http://svn.collab.net/viewvc/svn?view=revision&revision= # Subversion [$1]

  mod-wsgi    https://code.google.com/p/modwsgi/wiki/                 # mod_wsgi Wiki on Google Code
  mod-wsgi-issue  https://code.google.com/p/modwsgi/issues/detail?id= # mod_wsgi Issue Tracker on Google Code

  chromium-issue  https://code.google.com/p/chromium/issues/detail?id=

  Django      https://code.djangoproject.com/intertrac/ # Django's Trac
  AgileTrac   http://www.agile-trac.org/intertrac/     # Plugin adding Iterations to Trac

  CreoleWiki   http://wikicreole.org/wiki/
  Creole1Wiki  http://wikicreole.org/wiki/
  Creole2Wiki  http://wiki.wikicreole.org/

  MediaWiki    https://www.mediawiki.org/wiki/

  SO  https://stackoverflow.com/questions/ # Question $1 in StackOverflow

  Transifex https://www.transifex.com/projects/p/trac/

  kwquery      /query?group=status&keywords=~  # Custom query for tickets matching keyword $1

  #
  # A arbitrary pick of InterWiki prefixes...
  #
  Acronym          https://www.acronymfinder.com/$1.html
  C2find           http://c2.com/cgi/wiki?FindPage&value=
  Cache            https://www.google.com/search?q=cache:
  CPAN             https://search.cpan.org/perldoc?
  DebianBug        https://bugs.debian.org/
  DebianPackage    https://packages.debian.org/
  DebianPTS        https://packages.qa.debian.org/
  Dictionary       http://www.dict.org/bin/Dict?Database=*&Form=Dict1&Strategy=*&Query=
  Google           https://www.google.com/search?q=
  lmgtfy           https://lmgtfy.com/?q= # Well, just search for "$1", follow the link to see how to do it...
  GoogleGroups     https://groups.google.com/group/$1/msg/$2        # Message $2 in $1 Google Group
  gdiscussion      https://groups.google.com/d/topic/$1/$2/discussion # Discussion $2 in $1 Google
  gmessage         https://groups.google.com/d/msg/$1/$2 # Message $2 in $1 Google Group
  gforum           https://groups.google.com/forum/#!forum/$1 # Forum $1 in Google Groups
  JargonFile       http://downlode.org/perl/jargon-redirect.cgi?term=
  MeatBall         http://www.usemod.com/cgi-bin/mb.pl?
  MetaWiki         http://sunir.org/apps/meta.pl?
  MetaWikiPedia    https://meta.wikipedia.org/wiki/
  MoinMoin         https://moinmo.in/
  TracHacks        https://trac-hacks.org/wiki/
  OSM              https://wiki.openstreetmap.org/wiki/
  WhoIs            http://www.whois.sc/
  Why              http://clublet.com/c/c/why?
  c2Wiki           http://c2.com/cgi/wiki?
  WikiPedia        https://en.wikipedia.org/wiki/
  }}}


  ----
  See also: InterWiki, InterTrac


name: InterTrac
author: trac
text:
  = InterTrac Links

  Trac supports a convenient way to refer to resources of other Trac servers using Wiki markup. An !InterTrac link can be seen as a scoped [TracLinks TracLink]. It is used for referring to a Trac resource located in another Trac environment.

  == Link Syntax

  Simply use the name of the other Trac environment as a prefix, followed by a colon, ending with the resource located in the other environment:

  {{{
  <target_environment>:<TracLinks>
  }}}

  The other resource is specified using a regular !TracLink, of any flavor.

  That target environment name is either the real name of the environment or an alias.
  The aliases are defined in the `trac.ini` file, see below.
  The prefix is case insensitive.

  If the InterTrac link is enclosed in square brackets, like `[th:WikiExtrasPlugin]`, the InterTrac prefix is removed in the displayed link like a normal link resolver would be. For example, the above would be displayed as `WikiExtrasPlugin`.

  For convenience, there is also an alternate short-hand form, where an alias can be used as an immediate prefix for the identifier of a ticket, changeset or report, eg `#T234`, `[T1508]`, `[trac 1508]`.

  == Examples

  The only prefix defined by default is `trac`, which points to trac.edgewall.org. Additional prefixes can be specified in the [TracIni#intertrac-section intertrac] section of TracIni. For example:

  {{{#!ini
  [intertrac]
  # -- Example of setting up an alias:
  t = trac

  # -- Link to an external Trac:
  genshi.title = Edgewall's Trac for Genshi
  genshi.url = http://genshi.edgewall.org
  }}}

  The `.url` is mandatory and is used for locating the other Trac.
  It can be a relative URL when the Trac environment is located on the same server.

  The `.title` information is used in a tooltip, ie when hovering the cursor over an InterTrac link.

  Now, given the above configuration, one could create the following links:
   * to this InterTrac page:
     * `trac:wiki:InterTrac` trac:wiki:InterTrac
     * `t:wiki:InterTrac` t:wiki:InterTrac
     * `genshi:InterTrac` genshi:InterTrac
     * Keys are case insensitive: `T:wiki:InterTrac` T:wiki:InterTrac
   * to the ticket #234:
     * `trac:ticket:234` trac:ticket:234
     * `trac:#234` trac:#234
     * `genshi:#234` genshi:#234
     * `#T234` #T234
   * to the changeset [1912]:
     * `trac:changeset:1912` trac:changeset:1912
     * `[T1912]` [T1912]
   * to the log range [3300:3330]:
     * `trac:log:@3300:3330` trac:log:@3300:3330
     * `[trac 3300:3330]` [trac 3300:3330]
     * finally, to link to the start page of a remote trac, simply use its prefix followed by ':', inside an explicit link. Example: `[th: Trac Hacks]` (note that the ''remote'' Trac has to run Trac >= 0.11 for this to work'')

  The generic form `intertrac_prefix:module:id` is translated to the corresponding URL `<remote>/module/id`. Shorthand links are specific to some modules (e.g. !#T234 is processed by the ticket module). For the rest (`intertrac_prefix:something`), we rely on the [TracSearch#quickjump quick jump] facility of the remote Trac.

  == List of Active InterTrac Prefixes

  The following InterTrac prefixes are available on this site:

  [[InterTrac]]

  ----
  See also: TracLinks, InterWiki


name: InterWiki
author: trac
text:
  = Support for InterWiki links
  [[PageOutline(2-5,Contents,pullout)]]

  == Definition

  An InterWiki link can be used for referring to a Wiki page located in another Wiki system, and by extension, to any object located in any other Web application, provided a simple URL mapping can be done.

  InterWiki prefixes can even be used to introduce links to new protocols, such as `tsvn:` used by [trac:TortoiseSvn TortoiseSvn].

  == Link Syntax

  {{{
  <target_wiki>(:<identifier>)+
  }}}

  The link is composed by the targeted Wiki (or system) name, followed by a colon, eg `MeatBall:`, followed by a page specification in the target.
  Note that, as for InterTrac prefixes, '''InterWiki prefixes are case insensitive'''.

  The target Wiki URL is looked up in the [TracIni#interwiki-section "[interwiki]"] section of TracIni and in the InterMapTxt wiki page, modeled after MeatBall:InterMapTxt. If a prefix is defined in both the `[interwiki]` section and InterMapTxt, the `[interwiki]` section takes precedence.

  In addition to traditional !InterWiki links, where the target is simply ''appended'' to the URL, Trac supports parametric !InterWiki URLs:
  identifiers `$1`, `$2`, ... in the URL will be replaced by corresponding arguments.
  The argument list is formed by splitting the page identifier using the ":" separator.

  == [TracIni#interwiki-section "[interwiki]"]

  Every option in the `[interwiki]` section in TracIni 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:'''
  {{{#!ini
  [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
  }}}

  == Examples

  For the following excerpt of the InterMapTxt page:

  {{{
  = InterMapTxt =
  == This is the place for defining InterWiki prefixes ==

  Currently active prefixes: [[InterWiki]]

  This page is modelled after the MeatBall:InterMapTxt page.
  In addition, an optional comment is allowed after the mapping.
  ----
  {{{
  PEP      http://www.python.org/peps/pep-$1.html           # Python Enhancement Proposal $1
  Trac-ML  http://thread.gmane.org/gmane.comp.version-control.subversion.trac.general/$1  # Message $1 in Trac Mailing List

  tsvn     tsvn:                                            # Interact with TortoiseSvn
  ...
  MeatBall http://www.usemod.com/cgi-bin/mb.pl?
  MetaWiki http://sunir.org/apps/meta.pl?
  MetaWikiPedia http://meta.wikipedia.org/wiki/
  MoinMoin http://moinmoin.wikiwikiweb.de/
  ...
  }}}
  }}}

  Then,
   * `MoinMoin:InterWikiMap` will be rendered as MoinMoin:InterWikiMap and the ''title'' for that link will be "!InterWikiMap in !MoinMoin".
   * `Trac-ML:4346` will be rendered as Trac-ML:4346 and the ''title'' for that link will be "Message 4346 in Trac Mailing List".

  == List of Active Prefixes

  [[InterWiki]]

  ----
  See also: InterTrac, InterMapTxt


name: PageTemplates
author: trac
text:
  = Wiki Page Templates

  The default content for a new wiki page can be chosen from a list of page templates.

  The list is generated from all the wiki pages having a name starting with ''!PageTemplates/''.
  The initial content of a new page will simply be the content of the chosen template page, or a blank page if the special ''(blank page)'' entry is selected. When there are no wiki pages with the ''!PageTemplates/'' prefix, the initial content will always be the blank page and the template list selector will not be shown.

  To create a new template, simply create a new page having a name starting with ''!PageTemplates/''.

  Hint: one could even create a ''!PageTemplates/Template'' for facilitating the creation of new templates!

  After the first template has been created, a drop-down selection box will automatically appear on any new wiki page that is created. By default it is located on the right side of the ''Create this page'' button. The default selection will be ''blank page'', or ''!DefaultPage'' if ''!PageTemplates/DefaultPage'' exists.

  The following templates are available on this site:
  [[TitleIndex(PageTemplates/)]]

  ----
  See also: TracWiki


name: SandBox
author: trac
text:
  = The Sandbox =

  This is just a page to practice and learn WikiFormatting. 

  Go ahead, edit it freely.


name: TicketQuery
author: trac
text:
  = !TicketQuery Wiki Macro

  The !TicketQuery macro lets you display ticket information anywhere that accepts WikiFormatting.
  The query language used by the `[[TicketQuery]]` macro is described in the [TracQuery#QueryLanguage TracQuery] page.

  == Usage

  [[MacroList(TicketQuery)]]

  == Examples

  ||= **Example** =||= **Result** =||= **Macro** =||
  |-----------------------------------------------------------
  ||=Number of [query:status=new&milestone= Triage tickets]: =||\
  || **[[TicketQuery(status=new&milestone=,count)]]**||\
  || `[[TicketQuery(status=new&milestone=,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of new tickets: =||\
  || **[[TicketQuery(status=new,count)]]**||\
  || `[[TicketQuery(status=new,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of reopened tickets: =||\
  || **[[TicketQuery(status=reopened,count)]]**||\
  || `[[TicketQuery(status=reopened,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of assigned tickets: =||\
  || **[[TicketQuery(status=assigned,count)]]**||\
  || `[[TicketQuery(status=assigned,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of invalid tickets: =||\
  || **[[TicketQuery(status=closed,resolution=invalid,count)]]**||\
  || `[[TicketQuery(status=closed,resolution=invalid,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of worksforme tickets: =||\
  || **[[TicketQuery(status=closed,resolution=worksforme,count)]]**||\
  || `[[TicketQuery(status=closed,resolution=worksforme,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of duplicate tickets: =||\
  || **[[TicketQuery(status=closed,resolution=duplicate,count)]]**||\
  || `[[TicketQuery(status=closed,resolution=duplicate,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of wontfix tickets: =||\
  || **[[TicketQuery(status=closed,resolution=wontfix,count)]]**||\
  || `[[TicketQuery(status=closed,resolution=wontfix,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of fixed tickets: =||\
  || **[[TicketQuery(status=closed,resolution=fixed,count)]]**||\
  || `[[TicketQuery(status=closed,resolution=fixed,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of untriaged tickets (milestone unset): =||\
  || **[[TicketQuery(status!=closed,milestone=,count)]]**||\
  || `[[TicketQuery(status!=closed,milestone=,count)]]` ||
  |-----------------------------------------------------------
  ||=Total number of tickets: =||\
  || **[[TicketQuery(count)]]**||\
  || `[[TicketQuery(count)]]` ||
  |-----------------------------------------------------------
  ||=Number of tickets reported **or** owned by current user: =||\
  || **[[TicketQuery(reporter=$USER,or,owner=$USER,count)]]**||\
  || `[[TicketQuery(reporter=$USER,or,owner=$USER,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of tickets created this month: =||\
  || **[[TicketQuery(created=thismonth..,count)]]**||\
  || `[[TicketQuery(created=thismonth..,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of closed Firefox tickets: =||\
  || **[[TicketQuery(status=closed,keywords~=firefox,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=firefox,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of closed Opera tickets: =||\
  || **[[TicketQuery(status=closed,keywords~=opera,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=opera,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of closed tickets affecting Firefox and Opera: =||\
  || **[[TicketQuery(status=closed,keywords~=firefox opera,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=firefox opera,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of closed tickets affecting Firefox or Opera: =||\
  || **[[TicketQuery(status=closed,keywords~=firefox|opera,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=firefox|opera,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of tickets that affect Firefox or are closed and affect Opera: =||\
  || **[[TicketQuery(keywords~=firefox,or,status=closed,keywords~=opera,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=opera,or,keywords~=firefox,count)]]` ||
  |-----------------------------------------------------------
  ||=Number of closed Firefox tickets that don't affect Opera: =||\
  || **[[TicketQuery(status=closed,keywords~=firefox - opera,count)]]**||\
  || `[[TicketQuery(status=closed,keywords~=firefox -opera,count)]]` ||
  |-----------------------------------------------------------
  ||=Last 3 modified tickets: =||\
  ||**[[TicketQuery(max=3,order=modified,desc=1,compact)]]**||\
  || `[[TicketQuery(max=3,order=modified,desc=1,compact)]]` ||
  |-----------------------------------------------------------
  {{{#!th rowspan=2, style="text-align: left;"
  Details of ticket #1:
  }}}
  {{{#!td style="border-bottom: 0;"
  }}}
  {{{#!td
  `[[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]]`
  }}}
  |-
  {{{#!td colspan=2, style="border-top: 0;"
  [[TicketQuery(id=1,col=id|owner|reporter,rows=summary,table)]]
  }}}
  |-----------------------------------------------------------

  === Format: list

  {{{
  [[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
  }}}

  This is displayed as:
    [[TicketQuery(version=0.6|0.7&resolution=duplicate)]]

  {{{
  [[TicketQuery(id=123)]]
  }}}

  This is displayed as:
    [[TicketQuery(id=123)]]

  === Format: compact

  {{{
  [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
  }}}

  This is displayed as:
    [[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]

  === Format: count

  {{{
  [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
  }}}

  This is displayed as:
    [[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]

  === Format: progress

  {{{
  [[TicketQuery(milestone=0.12.8&group=type,format=progress)]]
  }}}

  This is displayed as:
    [[TicketQuery(milestone=0.12.8&group=type,format=progress)]]

  === Format: table

  You can choose the columns displayed in the table format (`format=table`) using `col=<field>`. You can specify multiple fields and the order they are displayed by placing pipes (`|`) between the columns:
  {{{
  [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
  }}}

  This is displayed as:
  [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]

  ==== Full rows

  In ''table'' format you can specify full rows using `rows=<field>`:
  {{{
  [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]
  }}}

  This is displayed as:
  [[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]

  ----
  See also: TracQuery, TracTickets, TracReports


name: TracAccessibility
author: trac
text:
  = Accessibility Support in Trac

  Not every user has a graphic environment with a mouse or other pointing device. Some users rely on a keyboard, alternative keyboard or voice input to navigate links and activate form controls. In a Trac session, users can use a device other than a pointing device by enabling keyboard shortcuts through the [/prefs/userinterface Keyboard Shortcuts] preferences panel.

  == Global Access Keys

  The global access keys differ by browser and the following work for several browsers:
   - on Linux, press any of the keys listed below in combination with the `<Alt>` key
   - on a Mac, use `<Ctrl>` + `<Opt>` + `<Key>`
   - on Windows, use `<Shift> + <Alt> + <Key>`. This works for the most common browsers, such as Firefox, Chrome, Safari and Internet Explorer

  See [wikipedia:Access_key#Access_in_different_browsers access in different browsers] for more details.

   * `1` - WikiStart
   * `2` - [TracTimeline Timeline]
   * `3` - [TracRoadmap Roadmap]
   * `4` - [TracSearch Search]
   * `6` - [TracGuide Trac Guide / Documentation]
   * `7` - [TracTickets New Ticket]
   * `9` - [/about About Trac]
   * `e` - Edit (wiki or report)
   * `r` - Preview (wiki or ticket)
   * `f` - Search

  == TracBrowser Navigation

  The browser can be navigated using the keys listed below. The key modifiers listed above are not used for navigating the browser.

  * `j` and `k` - select the next or previous entry, starting with the first
  * `o` ('''o'''pen) - toggle between expanded and collapsed state of the selected  directory or visit the selected file
  * `v` ('''v'''iew, '''v'''isit) and `<Enter>` - same as above
  * `r` - '''r'''eload an already expanded directory
  * `a` - directly visit a file in '''a'''nnotate (blame) mode
  * `L` - view the '''L'''og for the selected entry

  If no row has been selected using `j` or `k`, the keys will operate on the entry under the mouse.


name: TracAdmin
author: trac
text:
  = TracAdmin

  [[PageOutline(2-5, Contents, pullout)]]
  [[TracGuideToc]]

  Trac is distributed with a powerful command-line configuration tool. This tool can be used to configure and customize your Trac installation to better fit your needs.

  Some of the configurations can also be performed via the web administration module.

  == Usage

  For nearly every `trac-admin` command, the first argument must be the path to the TracEnvironment:
  {{{#!sh
  $ trac-admin /path/to/projenv wiki list
  }}}

  The only exception is for the `help` command, but even in this case, if you omit the environment you will only get a very succinct list of commands (`help` and `initenv`), the same list you would get when invoking `trac-admin` alone.
  `trac-admin --version` will tell you about the Trac version (e.g. 1.2) corresponding to the program.

  To get a comprehensive list of the available command and sub-command, specify the path to an environment:
  {{{#!sh
  $ trac-admin /path/to/projenv help
  }}}

  Some commands have more detailed help, which you can access by specifying the command's name as a subcommand for `help`:
  {{{#!sh
  $ trac-admin /path/to/projenv help <command>
  }}}

  When an error occurs in a `trac-admin` command the return value will be `2` and error messages are printed to `stderr`.

  === `trac-admin <targetdir> initenv` #initenv

  This subcommand is very important as is the one used to create a TracEnvironment in the specified `<targetdir>`. That directory must not exist prior to the call.

  [[TracAdminHelp(initenv)]]

  It supports the `--inherit` option, which specifies a global configuration file for sharing settings between several environments. You can also inherit from a shared configuration afterwards, by setting the `[inherit] file` option in the `conf/trac.ini` file in your newly created environment. The advantage of specifying the inherited configuration file at environment creation time is that only the options ''not'' specified in the global configuration file will be written to the environment's `conf/trac.ini` file.
  See TracIni#GlobalConfiguration.

  == Interactive Mode

  `trac-admin` starts in interactive mode when the environment path is the only argument.
  Commands can then be executed on the selected environment using the prompt, which offers tab-completion
  when the Python `readline` module is available. It also offers automatic repetition of the last command issued.

  The `readline` module should be available on all Unix-compatible platforms. For Windows, support can be obtained by installing [https://pypi.python.org/pypi/pyreadline pyreadline].

  Once you are in interactive mode, you can also get help on specific commands or subsets of commands:

  For example, to get an explanation of the `resync` command, run:
  {{{#!sh
  $ help resync
  }}}

  To get help on all the Wiki-related commands, run:
  {{{#!sh
  $ help wiki
  }}}

  == Full Command Reference

  You will find below the detailed help for all the commands available by default in `trac-admin`. Note that this may not match the list given by `trac-admin <yourenv> help`, as the commands pertaining to components disabled in that environment won't be available and conversely some plugins activated in the environment may add their own commands.

  [[TracAdminHelp()]]

  ----
  See also: TracBackup, TracEnvironment, TracIni, [trac:TracMigrate TracMigrate]


name: TracBackup
author: trac
text:
  = Trac Backup

  [[TracGuideToc]]

  Trac backups are a copied snapshot of the entire [TracEnvironment project environment] directory, including the database. Backups can be created using the `hotcopy` command of [TracAdmin trac-admin].

  '''Note''': Trac uses the `hotcopy` nomenclature to match that of [http://subversion.tigris.org/ Subversion], to make it easier to remember when managing both Trac and Subversion servers.

  == Creating a Backup

  Create a backup of a live TracEnvironment by running:
  {{{#!sh
  $ trac-admin /path/to/projenv hotcopy /path/to/backupdir
  }}}

  The database will be locked while hotcopy is running.

  The resulting backup directory is safe to handle using standard file-based backup tools like `tar` or `dump`/`restore`.

  Please note, the `hotcopy` command will not overwrite a target directory. When the target exists the operation will end with an error: `Command failed: [Errno 17] File exists:` This is discussed in [trac:#3198 #3198].

  == Restoring a Backup

  To restore an environment from a backup, stop the process running Trac, ie the web server or [TracStandalone tracd], restore the contents of your backup to your [TracEnvironment project environment] directory and restart the process.

  If you are using a database other than SQLite, you'll need to restore the database from the dump file. The dump file is saved in the environment `db` directory.

  To restore a PostgreSQL database backup, use the command:
  {{{#!sh
  $ psql -U <user> -d <database> -f /path/to/postgresql.dump
  }}}

  The `<database>` option is the same as the [TracEnvironment#DatabaseConnectionStrings database connection string] in the [TracIni#trac-database-option "[trac] database"] option of the project's `trac.ini` file.

  Similarly, for MySQL:

  {{{#!sh
  $ mysql -u <user> -p <database> < /path/to/mysql.dump
  }}}

  ----
  See also: TracAdmin, TracEnvironment, [trac:TracMigrate TracMigrate]


name: TracBatchModify
author: trac
text:
  = Trac Ticket Batch Modification =
  [[TracGuideToc]]

  Trac supports modifying a batch of tickets in one request from [TracQuery custom query] results. The Batch Modify functionality only appears on Query pages (/query), not Report pages (/report). You must have !JavaScript enabled in your browser.

  To perform a batch modification, select the tickets you wish to modify and set the new field values using the section underneath the query results.

  == List fields

  The `Keywords` and `Cc` fields are treated as lists, where list items can be added and/or removed, as well as replacing the entire list value. All list field controls accept multiple items, such as multiple keywords or cc addresses.

  == Excluded fields

  Multi-line text fields are not supported, because no valid use-case has been presented for syncing them across several tickets. That restriction applies to the `Description` field as well as to any [TracTicketsCustomFields#AvailableFieldTypesandOptions custom field] of type 'textarea'. However, future versions of Trac could support batch modification of textareas in conjunction with more suitable actions like 'prepend', 'append' or 'search & replace' ([trac:#11197]).


name: TracBrowser
author: trac
text:
  = The Trac Repository Browser

  [[TracGuideToc]]

  The Trac repository browser can be used to browse specific revisions of directories and files stored in the repositories associated with the Trac environment.

  At the top-level of the repository browser is the '''Repository Index''', listing all the configured repositories.
  Each repository has a name which is used as a path prefix in a "virtual" file hierarchy encompassing all the available repositories.
  One of the repositories can be configured with an empty name; this is the default repository. When such a default repository is present, its top-level files and directories are also listed, in a '''Default Repository''' section placed before the repository index. If the default repository is the only repository associated with the Trac environment, then the '''Repository Index''' will be omitted.

  Directory entries are displayed in a list with sortable columns. The list entries can be sorted by ''Name'', ''Size'', ''Age''/''Date'' or ''Author'' by clicking on the column headers. The third sortable column is labeled //Age// when the //Time format// [/prefs/localization preference] is //Relative// and //Date// when the //Time format// is //Absolute//. The sort order can be reversed by clicking on a given column header again.

  The browser can be used to navigate through the directory structure by clicking on the directory names.
  Clicking on a file name will show the contents of the file.
  Clicking on the revision number of a file or directory will take you to the TracRevisionLog for that file.
  Note that there's also a ''Revision Log'' navigation link that will do the same for the path currently being examined.
  Clicking on the ''diff'' icon after revision number will display the changes made to the files modified in that revision.
  Clicking on the ''Age''/''Date'' of the file - will take you to that changeset in the timeline.

  It's also possible to browse directories or files as they were in history, at any given repository revision. The default behavior is to display the latest revision but another revision number can easily be selected using the ''View revision'' input field at the top of the page.

  The color bar next to the ''Age''/''Date'' column gives a visual indication of the age of the last change to a file or directory, following the convention that '''[[span(style=color:#88f,blue)]]''' is oldest and '''[[span(style=color:#f88,red)]]''' is newest, but this can be [TracIni#browser-color_scale-option configured].

  At the top of the browser page, there's a ''Visit'' drop-down menu which you can use to select some interesting places in the repository, for example branches or tags.
  This is sometimes referred to as the ''browser quickjump'' facility.
  The precise meaning and content of this menu depends on your repository backend.
  For Subversion, this list contains by default the top-level trunk directory and sub-directories of the top-level branches and tags directories (`/trunk`, `/branches/*`, and `/tags/*`). This can be configured for more advanced cases through the `[svn]` [TracIni#svn-branches-option "branches"] and [TracIni#svn-tags-option "tags"] options.

  If you're using a Javascript enabled browser, you'll be able to expand and collapse directories in-place by clicking on the arrow head at the right side of a directory. Alternatively, the [TracAccessibility#TracBrowserAccessKeys keyboard shortcuts] can be used.

  For the Subversion backend, some advanced additional features are available:
   - The `svn:needs-lock` property is shown.
   - The `svn:mergeinfo` property shows eligible and merged revisions.
   - The `svn:externals` property can be [TracIni#svn:externals-section configured] to display a link to an external repository.
   - The `svn:mime-type` property is used to select the syntax highlighter for rendering the file. For example, setting `svn:mime-type` to `text/html` will ensure the file is highlighted as HTML, regardless of the file extension. It also allows selecting the character encoding used in the file content. For example, if the file content is encoded in UTF-8, set `svn:mime-type` to `text/html;charset=utf-8`. The `charset=` specification overrides the default encoding defined in the [TracIni#trac-default_charset-option "[trac] default_charset"] option.
  {{{#!comment
  MMM: I found this section a bit hard to understand. I changed the first item as I understood that well.
  but I think the other items could be changed also
   cboos: in the meantime, I've added the ''advanced'' word as a hint this can be a bit complex...
  }}}

  ----
  See also: TracChangeset, TracRevisionLog


name: TracCgi
author: trac
text:
  = Installing Trac as CGI
  [[TracGuideToc]]
  [[PageOutline]]

  {{{#!div class=important
   ''Please note that using Trac via CGI is the slowest deployment method available. It is slower than [wiki:TracModWSGI mod_wsgi], [TracModPython mod_python], [TracFastCgi FastCGI] and even [trac:TracOnWindowsIisAjp IIS/AJP] on Windows.''
  }}}

  CGI script is the entrypoint that web-server calls when a web-request to an application is made. The `trac.cgi` script can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. Make sure the script is executable by your web server.

  == Apache web-server configuration

  In [https://httpd.apache.org/ Apache] there are two ways to run Trac as CGI:

   1. Use a `ScriptAlias` directive that maps a URL to the `trac.cgi` script (recommended)
   1. Copy the `trac.cgi` file into the directory for CGI executables used by your web server (commonly named `cgi-bin`). You can also create a symbolic link, but in that case make sure that the `FollowSymLinks` option is enabled for the `cgi-bin` directory.

  To make Trac available at `http://yourhost.example.org/trac` add `ScriptAlias` directive to Apache configuration file, changing `trac.cgi` path to match your installation:
  {{{#!apache
  ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.cgi
  }}}

   ''Note that this directive requires that the `mod_alias` module is enabled.''

  If you're using Trac with a single project you need to set its location using the `TRAC_ENV` environment variable:
  {{{#!apache
  <Location "/trac">
    SetEnv TRAC_ENV "/path/to/projectenv"
  </Location>
  }}}

  Or to use multiple projects you can specify their common parent directory using the `TRAC_ENV_PARENT_DIR` variable:
  {{{#!apache
  <Location "/trac">
    SetEnv TRAC_ENV_PARENT_DIR "/path/to/project/parent/dir"
  </Location>
  }}}

    ''Note that the `SetEnv` directive requires that the `mod_env` module is enabled.''

  An alternative to `SetEnv` is editing `TRAC_ENV` or `TRAC_ENV_PARENT_DIR` in `trac.cgi`:

  {{{#!python
      os.environ['TRAC_ENV'] = "/path/to/projectenv"
  }}}

  {{{#!python
      os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/parent/dir"
  }}}

  If you are using the [https://httpd.apache.org/docs/suexec.html Apache suEXEC] feature please see [trac:ApacheSuexec].

  On some systems, you ''may'' need to edit the shebang line in the `trac.cgi` file to point to your real Python installation path. On a Windows system you may need to configure Windows to know how to execute a `.cgi` file (Explorer -> Tools -> Folder Options -> File Types -> CGI).

  === Python Egg Cache

  The [TracInstall#egg-cache egg-cache] can be configured using an `os.environ` statement in `trac.cgi`, as shown above.
  To do the same from the Apache configuration, use the `SetEnv` directive:
  {{{#!apache
  SetEnv PYTHON_EGG_CACHE /path/to/dir
  }}}

  Put this directive next to where you set the path to the [TracEnvironment Trac environment], i.e. in the same `<Location>` block.

  {{{#!apache
   <Location /trac>
     SetEnv TRAC_ENV /path/to/projenv
     SetEnv PYTHON_EGG_CACHE /path/to/dir
   </Location>
  }}}



  === Using WSGI

  You can run a [http://henry.precheur.org/python/how_to_serve_cgi WSGI handler] [https://thejimmyg.github.io/pythonweb/projects/webmodules/doc/0.5.3/html_multipage/lib/example-webserver-web-wsgi-simple-cgi.html under CGI].  You can [wiki:TracModWSGI#Thetrac.wsgiscript write your own application function], or use the deployed trac.wsgi's application.

  == Mapping Static Resources

  See TracInstall#MappingStaticResources.

  == Adding Authentication

  See TracInstall#ConfiguringAuthentication.

  ----
  See also:  TracInstall, [wiki:TracModWSGI], TracFastCgi, TracModPython


name: TracChangeLog
author: trac
text:
  [[PageOutline(2-3)]]
  = Change Log
  This is a rough list of changes between released versions.

  To see where Trac is going in future releases, see the [trac:roadmap Roadmap].

  == 1.5.x Releases

  === 1.5.2

  //(December 19, 2020)//

  Support for Python 2.7 has been dropped.
  Python 3.5+ is supported.

  [trac:source:/tags/trac-1.5.2 View Tag] | [trac:milestone:1.5.2 View Milestone]

  === 1.5.1

  //(May 25, 2020)//

  * Tickets can be retargeted from the milestone
    admin page ([trac:#3754]).
  * Removed deprecated code ([trac:#12787]).
    Plugins that use Genshi can't be used
    and must be migrated to Jinja2.

  Additionally, this release includes all of the
  changes in the [milestone:1.4.1] release and
  changes committed to date for the forthcoming [milestone:1.4.2] release.

  This will be the only release in the 1.5.x
  release line that supports Python 2.7. Future
  releases will support Python 3.5+.

  [trac:source:/tags/trac-1.5.1 View Tag] | [trac:milestone:1.5.1 View Milestone]

  == 1.4.x Releases

  === 1.4.1

  //(February 12, 2020)//

  Trac 1.4.1 fixes compatibility issues with
  Jinja2 versions 2.11 and 2.11.1. Several
  other minor defects were also fixed.

  [trac:source:/tags/trac-1.4.1 View Tag] | [trac:milestone:1.4.1 View Milestone]

  === '''1.4 'Jinja''''

  //(August 28, 2019)//

  Trac 1.4 is the first major release of Trac in almost 3 years.

  The following are some highlights from the release:

  * Jinja2 is the template engine, providing performance
    improvements over Genshi. Genshi is still supported
    until Trac 1.5.1 for rendering plugin templates.
  * Custom navigation items can be added to the
    main and meta navigation ([trac:#11317]).
  * TracAdmin `convert_db` command for
    converting to a new database backend while
    preserving all environment data
    ([trac:#12299]).
  * Restyled wiki that allows toggling between
    narrow and full width ([trac:#12640]).

  For more information see the [trac:wiki:TracDev/ApiChanges/1.4 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.4|1.4]] and the change log for [#a1.3.xReleases 1.3.x Releases] below.

  [trac:source:/tags/trac-1.4 View Tag] | [trac:milestone:1.4 View Milestone]

  == 1.3.x Releases

  // ** No guarantees of feature and API compatibility is made from one 1.3.x release to the next. //

  For more information see the [trac:wiki:TracDev/ApiChanges/1.3 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.3#DevelopmentReleases | 1.3]].

  === 1.3.6

  //(August 14, 2019)//

  Trac 1.3.6 provides several fixes and enhancements.

  * Permission groups added to the CC list will
    be resolved to members of the group ([trac:#12808]).
  * Auto preview timeout can be configured in user
    preferences ([trac:#12970]).
  * `TICKET_EDIT_CC` is required to edit the CC list
    for a new ticket ([trac:#13093]).

  [trac:source:/tags/trac-1.3.6 View Tag] | [trac:milestone:1.3.6 View Milestone]

  === 1.3.5

  //(July 17, 2019)//

  Trac 1.3.5 fixes a regression in the Ticket Clone feature.

  [trac:source:/tags/trac-1.3.5 View Tag] | [trac:milestone:1.3.5 View Milestone]

  === 1.3.4

  //(July 17, 2019)//

  Trac 1.3.4 provides a few fixes for the Jinja2
  template engine and template conversions.

  Additional highlights of changes since 1.3.3:
  * HTTPS support for TracStandalone (`tracd`)
    ([trac:#12611]).
  * Minor style improvements for ticket and wiki pages
    ([trac:#13116]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.4]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.18]] (as 1.3.4 contains the changes in 1.2.4 and 1.0.18).

  [trac:source:/tags/trac-1.3.4 View Tag] | [trac:milestone:1.3.4 View Milestone]

  === 1.3.3

  //(July 20, 2018)//

  Trac 1.3.3 provides many fixes for the Jinja2
  template engine and template conversions.

  Additional highlights of changes since 1.3.2:
  * The TracGuide is readonly by default ([trac:#12899]).
  * The `trac-svn-hook` script can be configured using
    SVN's hook script environment configuration ([trac:#12771]).
  * Environment log level defaults to `INFO` and log type
    defaults to `file` so that installation issue are captured
    in the log when running `trac-admin initenv` ([trac:#12966]).

  [trac:source:/tags/trac-1.3.3 View Tag] | [trac:milestone:1.3.3 View Milestone]

  === 1.3.2

  //(July 31, 2017)//

  Trac 1.3.2 is the first release to feature
  Jinja2 as the template engine. Jinja2 provides
  performance improvements and fixes several
  long-standing issues that were encountered
  using Genshi as the template engine. Genshi
  is still supported until Trac 1.5.1 for
  rendering plugin templates.

  Additional highlights of changes since 1.3.1:
  * All textareas that support wiki markup provide
    an auto-preview ([trac:#3776])
  * Ticket comments can be cloned to create a
    new ticket using the optional component
    `tracopt.ticket.clone`
    ([trac:#10735]).
  * Custom navigation items can be added to the
    main and meta navigation ([trac:#11317]).
  * Ticket validators are called when submitting
    a batch modification request ([trac:#11723]),
    and when editing a ticket comment
    ([trac:#12725]).
  * TracAdmin `convert_db` command for
    converting to a new database backend while
    preserving all environment data
    ([trac:#12299]).
  * Restyled wiki that allows toggling between
    narrow and full width ([trac:#12640]).

  [trac:source:/tags/trac-1.3.2 View Tag] | [trac:milestone:1.3.2 View Milestone]

  === 1.3.1

  //(November 15, 2016)//

  Trac 1.3.1 is the last release before the switch of the development branch to Jinja2.

  It is in sync with the version 1.2, and as such contains all its fixes and enhancements as well.

  Highlights of the changes since 1.2:

  * Modernized the code to support Python 2.7 idioms (earlier versions are no longer supported)
    ([trac:#12046], [trac:#12148], [trac:#12558], [trac:#12569])
  * Removed lots of backward compatibility APIs from pre-1.0 days;
    in particular, the database API is now exclusively based on the [[trac:wiki:TracDev/ApiChanges/1.1#DatabaseAPIChanges|context managers]] ([trac:#9612], [trac:#11901])
  * Ticket changes can be used to format the subject template ([trac:#12205])

  [trac:source:/tags/trac-1.3.1 View Tag] | [trac:milestone:1.3.1 View Milestone]


  == 1.2.x Releases

  This series correspond to the current stable release branch, i.e. [trac:source:branches/1.2-stable branches/1.2-stable].

  === 1.2.6

  //(July 1, 2020)//

  Trac 1.2.6 contains a few minor fixes, inluding a
  fix for ticket autopreview triggering without a
  form change.

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.6]].

  [trac:source:/tags/trac-1.2.6 View Tag] | [trac:milestone:1.2.6 View Milestone]

  === 1.2.5

  //(August 27, 2019)//

  Trac 1.2.5 contains a few minor fixes.

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.5]].

  [trac:source:/tags/trac-1.2.5 View Tag] | [trac:milestone:1.2.5 View Milestone]

  === 1.2.4

  //(July 17, 2019)//

  Trac 1.2.4 provides a dozen minor fixes and enhancements.

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.4]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.18]] (as 1.2.4 also contains the changes in 1.0.18).

  [trac:source:/tags/trac-1.2.4 View Tag] | [trac:milestone:1.2.4 View Milestone]

  === 1.2.3

  //(July 29, 2018)//

  Trac 1.2.3 provides 2 dozen minor fixes and enhancements.
  The following are some highlights:

  * Notification subscriber for New Tickets ([trac:#6613]).
  * Configurable HTTP headers ([trac:#12964]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.3]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.17]] (as 1.2.3 also contains the changes in 1.0.17).

  [trac:source:/tags/trac-1.2.3 View Tag] | [trac:milestone:1.2.3 View Milestone]

  === 1.2.2

  //(June 21, 2017)//

  Trac 1.2.2 provides close to 2 dozen minor fixes and enhancements.
  The following are some highlights:

  * Invalid logging configuration changes made through the
    //Logging// admin page won't disable a Trac instance ([trac:#8790]).
  * Fix for regression that prevented
    [https://trac-hacks.org/wiki/PermRedirectPlugin PermRedirectPlugin]
    from redirecting ([trac:#12818])

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.2]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.14]] through [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.15]] (as 1.2.2 also contains the changes in 1.0.14 and 1.0.15).

  [trac:source:/tags/trac-1.2.2 View Tag] | [trac:milestone:1.2.2 View Milestone]

  === 1.2.1

  //(March 29, 2017)//

  Trac 1.2.1, the first maintenance release in the 1.2.x series,
  provides more than 30 minor fixes and enhancements.
  The following are some highlights:

  * [WikiMacros#TracIni-macro TracIni macro] generates anchors for each option ([trac:#9401])
   and allows specifying exact options and sections to be rendered
   ([trac:#12633])
  * Several fixes for the enhanced Trac notification system
   ([trac:#11928], [trac:#12658], [trac:#12700])
  * Improved usability of ticket comment //Reply// and
   //Edit// buttons ([trac:#12671])
  * Restored missing ticket change conflict markers
   ([trac:#12730])

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2#MaintenanceReleases | 1.2.1]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.14]] (as 1.2.1 also contains the changes in 1.0.14).

  [trac:source:/tags/trac-1.2.1 View Tag] | [trac:milestone:1.2.1 View Milestone]

  === '''1.2 'Hermes''''

  //(November 5, 2016)//

  Trac 1.2 is the first major release of Trac in more than 4 years.

  The following are some highlights from the release:

  * Extensible notification system ([trac:#3517])
  * Notification preference panel ([trac:#4056])
  * Usernames replaced with full names ([trac:#7339])
  * Restyled ticket changelog ([trac:#11835])
  * Workflow controls on the //New Ticket// page ([trac:#2045])
  * Editable wiki page version comments ([trac:#6573])
  * Datetime custom fields ([trac:#1942])

  For more information see the [trac:wiki:TracDev/ApiChanges/1.2 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.2|1.2]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.8 through 1.0.13]]
  (as 1.2 contains all the fixes done for 1.0.8 through 1.0.13).

  [trac:source:/tags/trac-1.2 View Tag] | [trac:milestone:1.2 View Milestone]

  == 1.1.x Releases
  // 1.1.x releases were development releases leading to Trac 1.2. See them as kind of snapshots of [trac:source:trunk].

  ** No guarantees of feature and API compatibility is made from one 1.1.x release to the next. //

  === 1.2rc1

  //(September 14, 2016)//

  The first Trac 1.2 release candidate is the culmination of nearly 4 years of development.

  Highlights of the changes since 1.1.6:

   - Pygments lexer options can be specified as [WikiProcessors WikiProcessor] arguments and defaults can be set in the environment configuration ([trac:#5654]).
   - Usernames are replaced with full names when `[trac]` `show_full_names` is true ([trac:#7339]).
   - Enum tables on the Ticket Admin pages can be reordered by drag and drop. ([trac:#11682]).
   - Ticket changelog is restyled and has a new //Show comments// preference ([trac:#11835]).
   - Authentication cookies can be shared across subdomains when `[trac]` `auth_cookie_domain` is configured ([trac:#12251]).

  For more information see the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.2rc1]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.8 through 1.0.13]]
  (as 1.2rc1 contains all the fixes done for 1.0.8 through 1.0.13).

  [trac:source:/tags/trac-1.2rc1 View Tag] | [trac:milestone:1.2 View Milestone]

  === 1.1.6

  //(July 17, 2015)//

  Trac 1.1.6 contains more than a half dozen minor fixes and enhancements.

  For more information see the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.6]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.7]]
  (as 1.1.6 contains all the fixes done for 1.0.7).

  [trac:source:/tags/trac-1.1.6 View Tag] | [trac:milestone:1.1.6 View Milestone]


  === 1.1.5

  //(May 18, 2015)//

  Highlights of the changes:

   - Corrected highlighting of unmodified values in //Config// section of the //About Trac// page ([trac:#6551]).
   - New helper methods on `DatabaseManager` class for plugins to upgrade the database ([trac:#8172]).
   - New `[notification-subscriber]` config section for general configuration of notification subscription defaults and `SubscriberList` macro ([trac:#11875]).
   - Removed dependency on `ConfigObj` for TracFineGrainedPermissions ([trac:#11982]).
   - `Image` macro supports InterWiki prefixes ([trac:#12025]).

  See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.5]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.6]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.7]]
  (as 1.1.5 contains all the fixes done for 1.0.6 and 0.12.7).

  [trac:source:/tags/trac-1.1.5 View Tag] | [trac:milestone:1.1.5 View Milestone]

  === 1.1.4

  //(March 24, 2015)//

  Highlights of the changes:

   - Performance improvements with MySQL/MariaDB ([trac:#3676]).
   - Click on //Permissions// Admin page table row toggles all
     checkboxes in the row ([trac:#11417]).
   - Configuration sections are written to trac.ini when enabling a
     component through TracAdmin or the web administration module
     ([trac:#11437]).
   - Subscription rules can be reordered by drag and drop ([trac:#11941]).

  See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed
  release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.4]]
  and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.4/1.0.5]]
  (as 1.1.4 contains all the fixes done for 1.0.4 and 1.0.5).

  [trac:source:/tags/trac-1.1.4 View Tag] | [trac:milestone:1.1.4 View Milestone]

  === 1.1.3

  //(January 13, 2015)//

  The following list contains highlights of the changes:

   - The ticket creation step can be configured in the TracWorkflow and the
     workflow controls are present on the !NewTicket page ([trac:#2045]).
   - New notification system that can be extended by plugins ([trac:#3517]).
   - New preferences panel for notification subscriptions ([trac:#4056]).
   - Wiki page version comments can be edited by users with `WIKI_ADMIN` ([trac:#6573]).
   - Improved positioning of //Add Comment// section and //author// field
     on the ticket form ([trac:#10207]).
   - The delete confirmation pages warn if attachments will also be deleted
     ([trac:#11542]).
   - Removed support for [trac:SilverCity], Enscript and !PhpRenderer syntax
     highlighters ([trac:#11795]).
   - Combined //Date & Time// and //Language// preference panels as
     //Localization// ([trac:#11813]).
   - Groups and permissions can be used in the workflow `set_owner` attribute
     ([trac:#11839]).

  See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.3]] and [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.3]] (as 1.1.3 contains all the fixes done
  for 1.0.3).

  [trac:source:/tags/trac-1.1.3 View Tag] | [trac:milestone:1.1.3 View Milestone]

  === 1.1.2

  //(October 23, 2014)//

  The following list contains highlights of the changes:

   - Dropped support for Python 2.5. Trac can no longer be run on Python 2.5 as incompatible changes have been made in the source code ([trac:#11600]).
   - The new ticket workflow action `may_set_owner` is similar to `set_owner` but the owner defaults to the existing ticket owner rather than the current user ([trac:#10018]).
   - The new option `[ticket]` `optional_fields` specifies ticket select fields that are treated as optional (i.e. an empty value is allowed) ([trac:#10772]).
   - Line number and row highlighting annotations can be specified for !WikiProcessor code blocks ([trac:#10834]).
   - The //default handler// can be set as a session preference ([trac:#11597]), and the default value for all users can be set from the //Basic Settings// admin page ([trac:#11519]).
   - Attachments can't be added to read-only wiki pages ([trac:#11244]).
   - Tables on the admin pages have a //Select all// checkbox in the header ([trac:#10994]).
   - Submit buttons are disabled if the required items are not selected ([trac:#11056]).
   - The Admin //Permissions// page has a //Copy Permissions// form for copying permissions between users and groups ([trac:#11099]).
   - The new option `[milestone]` `default_retarget_to` determines the default milestone for retargeting tickets when a milestone is deleted or closed, and can be specified from the //Milestone// admin page ([trac:#10010]).
   - The //retarget// select is not shown when closing or deleting a milestone which has no tickets associated with it ([trac:#11366]).
   - //Clear default// buttons allow the ticket system default values (e.g. `default_milestone`, `default_version`) to be cleared through the corresponding admin pages ([trac:#10772], [trac:#11300]).
   - The `TitleIndex` macro supports relative path prefixes when used on wiki pages ([trac:#11455]).
   - [trac:CommitTicketUpdater] will recognize a ticket reference that includes a trailing `#comment:N` or `#comment:description` ([trac:#11622]).
   - The //Tickets// column of the milestone table on the //Milestone// admin page contains links to the query page showing all tickets associated with the milestone, grouped by status ([trac:#11661]).
   - Authz policy can be used to restrict access to the //Report List// page using the resource id `-1` ([trac:#11697]).

  See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.2]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.2]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.6]] (as 1.1.2 contains all the fixes done for 1.0.2 and 0.12.6).

  [trac:source:/tags/trac-1.1.2 View Tag] | [trac:milestone:1.1.2 View Milestone]

  === 1.1.1

  //(February 3, 2013)//

  Trac 1.1.1 starts the 1.1.x development line leading to 1.2 with some new features and a few not-so-disruptive changes.

  The following list contains only a few highlights:

   - Added support for custom ticket fields of type time ([trac:#1942])
   - In new tickets, custom time ticket fields may default to an absolute or relative date / time ([trac:#10853])
   - In TracBatchModify, custom time ticket fields can be changed with a date(time)picker popup control ([trac:#10854])
   - Optionally display the component of tickets in their timeline entries (`[timeline]` `ticket_show_component` setting) ([trac:#10885])
   - Fixed batch modification when no fields are changed ([trac:#10924])
   - Dynamic variables can be used in the report title and description ([trac:#10979])
   - jQuery upgraded to 1.8.3, jQuery UI upgraded to 1.9.2 and jQuery UI Timepicker upgraded to 1.1.1 ([trac:#10976])
   - Dropped support for Python 2.5, either Python 2.6 or Python 2.7 is required //(well, as it happens, 2.5 //still// works, that's a bug ;-) )//

  See also the [trac:wiki:TracDev/ApiChanges/1.1 API changes] and the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.1#DevelopmentReleases | 1.1.1]], [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.1]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.5]] (as 1.1.1 contains all the fixes done for 1.0.1 and 0.12.5).

  [trac:source:/tags/trac-1.1.1 View Tag] | [trac:milestone:1.1.1 View Milestone]

  == 1.0.x Releases

  === 1.0.20

  //(June 29, 2020)//

  Trac 1.0.20 provides a few bug fixes. The translation
  catalogs have also been updated and merged with
  those from Transifex.

  [trac:source:/tags/trac-1.0.20 View Tag] | [trac:milestone:1.0.20 View Milestone]

  === 1.0.19

  //(October 15, 2019)//

  Trac 1.0.19 provides a few bug fixes. The translation
  catalogs have also been updated and merged with
  those from Transifex.

  [trac:source:/tags/trac-1.0.19 View Tag] | [trac:milestone:1.0.19 View Milestone]

  === 1.0.18

  //(July 18, 2019)//

  Trac 1.0.18 provides more than a dozen bug fixes and minor
  enhancements. The following are some highlights:

   * Fixed query module regression when ordering
     multiple columns ([trac:#13068]).
   * Fixed regression preventing workflow status
     changes for plugins ([trac:#13087]).
   * Made compatible with MySQL 8.x ([trac:#13128]).

  [trac:source:/tags/trac-1.0.18 View Tag] | [trac:milestone:1.0.18 View Milestone]

  === 1.0.17

  //(July 11, 2018)//

  Trac 1.0.17 provides more than 3 dozen bug fixes and minor
  enhancements. The following are some highlights:

   * Fixed `ERR_BLOCKED_BY_XSS_AUDITOR` during preview for
     certain content with Chrome browser ([trac:#12926]).
   * Improved performance of query module when many custom
     fields are used ([trac:#12967]).
   * Fixed ticket description not rendered in wiki format in
     query view ([trac:#13010]).
   * Added submodule support for Git repository ([trac:#10603])

  [trac:source:/tags/trac-1.0.17 View Tag] | [trac:milestone:1.0.17 View Milestone]

  === 1.0.16

  //Not Released//

  === 1.0.15

  //(June 16, 2017)//

  Trac 1.0.15 adds an option `[wiki]` `safe_origins`, for whitelisting URIs considered //safe cross-origin//.

  [trac:source:/tags/trac-1.0.15 View Tag] | [trac:milestone:1.0.15 View Milestone]

  === 1.0.14

  //(June 9, 2017)//

  Trac 1.0.14 provides more than 3 dozen bug fixes and minor
  enhancements. The following are some highlights:

   - Improved Git performance ([trac:#12545], [trac:#12694]).
   - Reduced memory usage exporting a zip file ([trac:#12765]).
   - Fixed batch modify not working for list fields
     (regression in 1.0.11) ([trac:#12585]).
   - Performance improvements to the Roadmap and Milestone
     admin pages when there are many milestones and tickets
     ([trac:#12609]).
   - SECURITY: Possible XSS via reStructuredText link.
   - SECURITY: Injection of password prompt using Image
     macro or reStructuredText image.

  [trac:source:/tags/trac-1.0.14 View Tag] | [trac:milestone:1.0.14 View Milestone]

  === 1.0.13

  //(September 11, 2016)//

  Trac 1.0.13 provides around a dozen bug fixes and minor
  enhancements. The following are some highlights:

   - Use locale environment variables to negotiate locale
     on console ([trac:#12418]).
   - Fixed using incorrect revisions when downloading a zip
     file via browser page from Git repository ([trac:#12557]).

  [trac:source:/tags/trac-1.0.13 View Tag] | [trac:milestone:1.0.13 View Milestone]

  === 1.0.12

  //(July 4, 2016)//

  Trac 1.0.12 provides around 20 bug fixes and minor enhancements. The following are some highlights:

   - Reconnect to PostgreSQL server after restarting it
     ([trac:#4984]).
   - Workflow actions on the batch modify form are sorted
     by the default attribute ([trac:#12447]).
   - Fixed Pygments stylesheet not found when style name
     contained a dash ([trac:#12505]).
   - Fixed incorrect parsing of projects list file by
     `GitwebProjectsRepositoryProvider` ([trac:#12518]).
   - `TracIni` macro displays option documentation as
     multi-line rather than one-liner ([trac:#12522]).
   - Fixed regression with `GitConnector` leading to
     `IOError: Too many open files` ([trac:#12524]).

  [trac:source:/tags/trac-1.0.12 View Tag] | [trac:milestone:1.0.12 View Milestone]

  === 1.0.11

  //(May 7, 2016)//

  Trac 1.0.11 provides more than 30 bug fixes and minor
  enhancements. As in 1.0.10, an area of focus has been to
  eliminate tracebacks in the logs due to invalid requests.
  The following are some additional highlights:

   - Fixed resetting //Oldest first// after auto-preview of
     ticket change log ([trac:#12381]).
   - Trac is now distributed as wheel package ([trac:#12391]).
   - Fixed database exceptions in query system when
     ''milestones/versions/enums'' are not defined and a custom
     field of the same name is added ([trac:#12399]).
   - Custom field //milestone// was not shown when
     standard //milestone// field was hidden ([trac:#12400]).
   - Query system now sorts by `enum.value` rather than
     `ticket.type` for `order=type` ([trac:#12402]).
   - Added support for Babel 2.3.2 (2.3.0 and 2.3.1 should
     not be used)  ([trac:#12445]).

  [trac:source:/tags/trac-1.0.11 View Tag] | [trac:milestone:1.0.11 View Milestone]

  === 1.0.10

  //(February 20, 2016)//

  Trac 1.0.10 provides more than 30 bug fixes and minor enhancements. Two areas of focus
  have been fixing test failures on Windows and eliminating tracebacks in the logs due to
  invalid requests.

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.10]].

  [trac:source:/tags/trac-1.0.10 View Tag] | [trac:milestone:1.0.10 View Milestone]

  === 1.0.9

  //(September 10, 2015)//

  Trac 1.0.9 provides more than a dozen minor fixes and enhancements, including significantly reduced memory usage by the Git repository connector.

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.9]].

  [trac:source:/tags/trac-1.0.9 View Tag] | [trac:milestone:1.0.9 View Milestone]

  === 1.0.8

  //(July 24, 2015)//

  Trac 1.0.8 fixes a regression introduced in Trac 1.0.7: the session
  for an authenticated username containing non-alphanumeric characters
  could not be retrieved, resulting in the user being denied access to
  every realm and resource ([trac:#12129]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.8]].

  [trac:source:/tags/trac-1.0.8 View Tag] | [trac:milestone:1.0.8 View Milestone]

  === 1.0.7

  //(July 17, 2015)//

  Trac 1.0.7 contains more than a dozen minor fixes and enhancements, including the following highlights:
   - Custom `svn:keywords` definitions are expanded in Subversion 1.8 and later ([trac:#11364]).
   - Fixed MySQL performance regression in query with custom fields ([trac:#12113]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.7]].

  [trac:source:/tags/trac-1.0.7 View Tag] | [trac:milestone:1.0.7 View Milestone]

  === 1.0.6

  //(May 20, 2015)//

  Trac 1.0.6 provides more than 20 fixes and enhancements. The following are some highlights:
   - Hash changeset ids and branch names can be used in revision ranges ([trac:#11050])
   - Improved rendering performance using chunked response when `[trac]` `use_chunked_encoding` is `True` ([trac:#11802])
   - Improved performance of Git repositories ([trac:#11971]).
   - Header to send when `[trac]` `use_xsendfile` is `True` can be specified through the option `[trac]` `xsendfile_header`. X-Sendfile is supported in Nginx by specifying `X-Accel-Redirect` for the header ([trac:#11981]).
   - Symbolic link can be used for `conf/trac.ini` in environment directory ([trac:#12000]).
   - Hyphen character can be used in !WikiProcessor parameter name ([trac:#12023]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.6]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.7]] (as 1.0.6 also contains the changes in 0.12.7).

  [trac:source:/tags/trac-1.0.6 View Tag] | [trac:milestone:1.0.6 View Milestone]

  === 1.0.5

  //(March 24, 2015)//

  Trac 1.0.5 provides several fixes. The following are some highlights:

   - Images are not rendered in the timeline ([trac:#10751]).
   - Git tags are shown in the browser view ([trac:#11964]).
   - Added support for `journal_mode` and `synchronous` pragmas
     in `sqlite:` database connection string ([trac:#11967]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.5]].

  [trac:source:/tags/trac-1.0.5 View Tag] | [trac:milestone:1.0.5 View Milestone]

  === 1.0.4

  //(February 8, 2015)//

  Trac 1.0.4 contains a few fixes, including a fix for a regression in 1.0.3.

   - Workflow action labels were not displayed unless name attribute
     was explicitly defined ([trac:#11930]).

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.4]].

  [trac:source:/tags/trac-1.0.4 View Tag] | [trac:milestone:1.0.4 View Milestone]

  === 1.0.3

  //(January 13, 2015)//

  Trac 1.0.3 is a maintenance release containing numerous fixes and minor
  enhancements. The following are a few of the highlights:

  The following list contains only a few highlights:

   - Notification is sent when adding an attachment to a ticket ([trac:#2259]).
   - Stylesheets and scripts are loaded during autopreview, resulting in proper
     syntax highlighting when code WikiProcessors are added ([trac:#10470]) and display
     of Workflow graphs without explicit autopreview ([trac:#10674]).
   - Merge changesets are shown as differences against first parent, resulting
     in less noisy changesets ([trac:#10740]).
   - Pygments 2.0 is supported ([trac:#11796]).
   - Fixed error when completing the `initenv` TracAdmin command ([trac:#11797]).
   - Performance improvement on systems with many thousands of authenticated
     users due to caching of Environment.get_known_users ([trac:#11868]).
   - Distribution metadata of wheel package is supported and displayed on the
     About page ([trac:#11877]).
   - … and more than 3 dozen total fixes!

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.3]].

  [trac:source:/tags/trac-1.0.3 View Tag] | [trac:milestone:1.0.3 View Milestone]


  === 1.0.2

  //(October 23, 2014)//

  Trac 1.0.2 contains a number of bug fixes and minor enhancements, as well as a major update for many translations.

  The following list contains only a few highlights:

   - Subversion keywords are expanded and EOL substitutions made when viewing a file in the repository browser and when downloading a file ([trac:#717]).
   - Notification email is sent to the old owner when a ticket is reassigned ([trac:#2311]).
   - Ticket change history is updated when renaming and deleting a milestone, and when retargeting tickets to another milestone ([trac:#4582], [trac:#5658]).
   - Numerous fixes for the Authz permissions policy in the browser/repository ([trac:#10961], [trac:#11646]), wiki ([trac:#8976], [trac:#11067]), admin ([trac:#11069]) and report ([trac:#11176]) realms.
   - Multiple forms submits are disallowed ([trac:#10138]).
   - `ConfigurationError` is raised if any of the `permission_policies` can't be loaded, preventing possible information leakage due to internal and installation errors ([trac:#10285]).
   - Wiki toolbars can be disabled through a configuration setting ([trac:#10837])
   - The number of entries in a table is shown next to heading on applicable admin pages ([trac:#11027]).
   - //Cancel// buttons are consistently located on all pages ([trac:#11076]).
   - Focus is placed on a text element when an edit page is loaded ([trac:#11084]).
   - The //Edit conflict// and //Merge// warning messages are always visible in side-by-side edit mode ([trac:#11102]).
   - Improvements to the layout of the Report ([trac:#11106], [trac:#11664]) and Ticket pages ([trac:#11471]).
   - Genshi 0.7 compatibility ([trac:#11218]).
   - Numerous minor fixes for Git repository support.
   - … and more than a hundred more fixes!

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.2]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.6]] (as 1.0.2 contains all the fixes done for 0.12.6).

  [trac:source:/tags/trac-1.0.2 View Tag] | [trac:milestone:1.0.2 View Milestone]


  === 1.0.1

  //(February 1, 2013)//

  Trac 1.0.1 contains a number of bug fixes and minor enhancements, as well as a major update for many translations.

  The following list contains only a few highlights:

   - Fix zip source download for large directories in Subversion repositories ([trac:#10840])
   - Performance improvement for the Roadmap, by caching milestone properties ([trac:#10879])
   - Added a ''select all'' checkbox to table of components for each plugin on the Plugins admin panel ([trac:#9609])
   - Restore the ''Modify'' link at the top of the ticket page, as it was in Trac 0.12 ([trac:#10856])
   - `ListOption` keeps values other than empty string and None in raw list as default ([trac:#10541])
   - Prevent possibility of multiple identical info or warning messages being presented to the user ([trac:#10987])
   - The !BatchModify select-all checkboxes are toggled with tri-state behavior when the ticket checkboxes are toggled ([trac:#10992])
   - Update the ticket changetime to the current time when deleting a ticket comment ([trac:#10486])

  See the detailed release notes for [[trac:wiki:TracDev/ReleaseNotes/1.0#MaintenanceReleases | 1.0.1]] and [[trac:wiki:TracDev/ReleaseNotes/0.12#MaintenanceReleases | 0.12.5]] (as 1.0.1 contains all the fixes done for 0.12.5).

  [trac:source:/tags/trac-1.0.1 View Tag] | [trac:milestone:1.0.1 View Milestone]


  === '''1.0 'Cell' '''

  //(September 7, 2012)//

  Trac 1.0 is a major release adding refreshed user interface and improved DVCS repository support as the most visible changes.

  The following list contains only a few highlights:
   - The default theme looks more modern, especially on recent browsers (no effort has been made to make it look better on older browsers like IE6 or 7)
   - The [TH:GitPlugin] has been donated by Herbert Valerio Riedel to the Trac project (many thanks!) and is now maintained here as an optional component
   - As a consequence, the Subversion support has been moved below `tracopt.versioncontrol` as well
   - The Git and Mercurial log view feature a visualization of the branching structure
   - Usability improvements for the tickets, with a better support for conflict detection and resolution
   - Integration of the [TH:BatchModifyPlugin], contributed by Brian Meeker (many thanks!) and is now maintained there as a default component
   - jQuery/UI integration, featuring a date picker for date fields
   - Improved integration with Pygments syntax highlighting
   - ... and numerous smaller features added and bugs fixed since 0.12!

  See the full list in [trac:wiki:TracDev/ReleaseNotes/1.0 1.0].

  [trac:source:/tags/trac-1.0 View Tag] | [trac:milestone:1.0 View Milestone]

  == Older Releases

  For releases prior to 1.0, see [trac:TracChangeLog@154#a0.12.xReleases TracChangeLog@154].

  For releases prior to 0.12, see [trac:TracChangeLog@95#a0.11.xReleases TracChangeLog@95].


name: TracChangeset
author: trac
text:
  = Trac Changeset Module

  [[TracGuideToc]]
  [[PageOutline(2-5,Contents,pullout)]]

  Trac has a built-in functionality for visualizing "diffs", or changes to files.

  There are different kinds of ''change sets''.  Some correspond to revisions made in the repositories, others aggregate changes made in several revisions. Ultimately, any kind of difference can be shown.

  The changeset view consists of two parts, the ''header'' and the ''diff views''.

  == Changeset Header

  The header shows an overview of the whole changeset.
  Here you will find metadata:

   * Timestamp — When the changeset was commited
   * Author — Who commited the changeset
   * Message — A brief description from the author (the commit log message)
   * Location — Parent directory of all files affected by this changeset
   * Files — A list of files affected by this changeset

  If more than one revision is involved in the set of changes being displayed, the ''Timestamp'', ''Author'' and ''Message'' fields will not be shown.

  A colored rectangle indicates how the file is affected by the changeset:

   [[span(style=background:#bfb;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Green: Added \\
   [[span(style=background:#f88;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Red: Removed \\
   [[span(style=background:#fd8;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Yellow: Modified \\
   [[span(style=background:#88f;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Blue: Copied \\
   [[span(style=background:#ccc;border:1px solid #999;font-size:80%;margin-right:.5em,''  '')]] Gray: Moved \\

  The color legend is located below the header.

  == Diff Views

  Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section. There are two different diff styles: ''inline'' and ''side-by-side''. You can switch between the styles using the preferences form:

   * The ''inline'' style shows the changed regions of a file underneath each other. A region removed from the file will be colored red, an added region will be colored green. If a region was modified, the old version is displayed above the new version. Line numbers indicate the exact position of the change in both the old and the new version of the file.
   * The ''side-by-side'' style shows the old version on the left and the new version on the right and this will typically require more screen width than the inline style. Added and removed regions will be colored in the same way as with the inline style (green and red), and modified regions will have a yellow background.

  In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
   * You can set how many lines are displayed before and after every change, or display the changes in the context of the full file.
   * You can toggle whether blank lines, case changes and white space changes are ignored. This can be useful in more easily locating the functional changes.
   * You can toggle between contextual and unified diff views using the //Tabular// and //Unified// links at the top of each section.

  == The Different Ways to Get a Diff

  === Examining a Changeset

  When viewing a repository check-in, such as when following a changeset [TracLinks link] or a changeset event in the [TracTimeline timeline], Trac will display the exact changes made by the check-in.

  There will also be navigation links to the ''Previous Changeset'' and the ''Next Changeset''.

  === Downloading a Changeset

  From the changeset view, the changeset can be downloaded in unified diff format using the links at the bottom of the page. The full content of each file in the changeset can also be downloaded as a zip archive.

  === Examining Differences Between Revisions

  Often you want to look at changes made on a file or on a directory spanning multiple revisions. The easiest way to get there is from the TracRevisionLog, where you can select the ''old'' and the ''new'' revisions of the file or directory, and then click the ''View changes'' button.

  === Examining Differences Between Branches

  One of the core features of version control systems is the possibility to work simultaneously on different ''Lines of Developments'', commonly called "branches". Trac enables you to examine the exact differences between such branches.

  Following the '''View changes ...''' button in the TracBrowser leads to the diff page, where you can enter ''From:'' and ''To:'' path/revision pairs. The resulting set of differences consist of the changes that should be applied to the ''From:'' content to get to the ''To:'' content.

  For convenience, it is possible to invert the roles of the ''old'' and the ''new'' path/revision pairs by clicking the ''Reverse Diff'' link on the changeset page.

  === Checking the Last Change

  Another way to examine changes is to use the ''Last Change'' link provided by the TracBrowser.

  This link will take you to the last change that was made on that path. From there, you can use the ''Previous Change'' and ''Next Change'' links to traverse the change history of the file or directory.

  ----
  See also: TracGuide, TracBrowser


name: TracEnvironment
author: trac
text:
  = The Trac Environment

  [[TracGuideToc]]
  [[PageOutline(2-5,Contents,pullout)]]

  Trac uses a directory structure and a database for storing project data. The directory is referred to as the '''environment'''.

  Trac supports [https://www.sqlite.org/ SQLite], [https://www.postgresql.org/ PostgreSQL] and [https://www.mysql.com/ MySQL] databases. With PostgreSQL and MySQL you have to create the database before running `trac-admin initenv`.

  == Creating an Environment

  A new Trac environment is created using the [TracAdmin#initenv initenv] command:
  {{{#!sh
  $ trac-admin /path/to/myproject initenv
  }}}

  `trac-admin` will ask you for the name of the project and the [#DatabaseConnectionStrings database connection string].

  A base configuration can be specified using the `--inherit` or `--config` options. The `--inherit` option can be specified one or more times to utilize a [TracIni#GlobalConfiguration global configuration]. The options specified in a `--config` file will be used to override the defaults when initializing `trac.ini`. See below for an [#SourceCodeRepository example] of defining repositories in a configuration file.

  === Useful Tips

   - Place your environment's directory on a filesystem which supports sub-second timestamps, as Trac monitors the timestamp of its configuration files and changes happening on a filesystem with too coarse-grained timestamp resolution may go undetected in Trac < 1.0.2. This is also true for the location of authentication files when using TracStandalone.

   - The user under which the web server runs will require file system write permission to the environment directory and all the files inside. Please remember to set the appropriate permissions. The same applies to the source code repository, although the user under which Trac runs will only require write access to a Subversion repository created with the BDB file system; for other repository types, check the corresponding plugin's documentation.

   - Non-ascii environment paths are not supported.

   - TracPlugins located in a [TracIni#inherit-plugins_dir-option shared plugins directory] that is defined in an [TracIni#GlobalConfiguration inherited configuration] are not enabled by default, in contrast to plugins in the environment `plugins` directory. Hence, if they need to create extra tables, for example, the tables will not be created during environment creation and you'll need to [TracUpgrade#UpgradetheTracEnvironment upgrade the environment]. Alternatively you can avoid the need to upgrade the environment by explicitly enabling the plugin(s) in a configuration file using the `--inherit` or `--config` option. See TracAdmin#FullCommandReference for more information.

  {{{#!div style="border: 1pt dotted; margin: 1em;"
  **Caveat:** don't confuse the //Trac environment directory// with the //source code repository directory//.

  This is a common beginners' mistake.
  It happens that the structure for a Trac environment is loosely modeled after the Subversion repository directory structure, but those are two disjoint entities and they are not and //must not// be located at the same place.
  }}}

  == Database Connection Strings

  You will need to specify a database connection string at the time the environment is created. The default is SQLite, which is sufficient for most projects. The SQLite database file is stored in the environment directory, and can easily be [wiki:TracBackup backed up] together with the rest of the environment.

  Note that if the username or password of the connection string (if applicable) contains the `:`, `/` or `@` characters, they need to be [https://meyerweb.com/eric/tools/dencoder/ URL encoded].
  {{{#!sh
  $ python -c "import urllib; print urllib.quote('password@:/123', '')"
  password%40%3A%2F123
  }}}

  === SQLite Connection String

  The connection string for an SQLite database is:
  {{{
  sqlite:db/trac.db
  }}}
  where `db/trac.db` is the path to the database file within the Trac environment.

  See [trac:DatabaseBackend#SQLite] for more information.

  === PostgreSQL Connection String

  The connection string for PostgreSQL is a bit more complex. For example, to connect to a PostgreSQL database named `trac` on `localhost` for user `johndoe` and password `letmein`, use:
  {{{
  postgres://johndoe:letmein@localhost/trac
  }}}

  If PostgreSQL is running on a non-standard port, for example 9342, use:
  {{{
  postgres://johndoe:letmein@localhost:9342/trac
  }}}

  On UNIX, you might want to select a UNIX socket for the transport, either the default socket as defined by the PGHOST environment variable:
  {{{
  postgres://user:password@/database
  }}}

  or a specific one:
  {{{
  postgres://user:password@/database?host=/path/to/socket/dir
  }}}

  See the [https://www.postgresql.org/docs/ PostgreSQL documentation] for detailed instructions on how to administer [https://www.postgresql.org/ PostgreSQL].
  Generally, the following is sufficient to create a database user named `tracuser` and a database named `trac`:
  {{{#!sh
  $ createuser -U postgres -E -P tracuser
  $ createdb -U postgres -O tracuser -E UTF8 trac
  }}}

  When running `createuser` you will be prompted for the password for the `tracuser`. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a Trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command. Also note that the database should be created as UTF8. LATIN1 encoding causes errors, because of Trac's use of unicode.

  Under some default configurations (Debian), run the `createuser` and `createdb` scripts as the `postgres` user:
  {{{#!sh
  $ sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser'
  $ sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac'
  }}}

  Trac uses the `public` schema by default, but you can specify a different schema in the connection string:
  {{{
  postgres://user:pass@server/database?schema=yourschemaname
  }}}

  === MySQL Connection String

  The format of the MySQL connection string is similar to PostgreSQL, with the `postgres` scheme being replaced by `mysql`. For example, to connect to a MySQL database on `localhost` named `trac` for user `johndoe` with password `letmein`:
  {{{
  mysql://johndoe:letmein@localhost:3306/trac
  }}}

  === Changing Database Backend

  The TracAdmin `convert_db` command allows migrating between SQLite, MySQL and PostgreSQL databases.

  [[TracAdminHelp(convert_db)]]

  == Deleting a Trac Environment

  The Trac environment can be deleted using standard filesystem utilities to delete the directory that was passed to the `initenv` command. For an environment using SQLite, this will also delete the SQLite database, which resides on-disk in the environment `db` directory. For an environment using PostgreSQL or MySQL, you will need to use the associated database utilities to delete the database.

  == Source Code Repository

  A single environment can be connected to more than one repository. However, by default Trac is not connected to any source code repository, and the ''Browse Source'' navigation item will not be displayed. There are several ways to connect repositories to an environment, see TracRepositoryAdmin.

  Repositories can be defined at the time of environment creation by specifying a configuration file to the `initenv` command using the `--config` or `--inherit` options. Cached repositories will be synchronized if the repository connector(s) are enabled. Example:

  {{{#!sh
  $ trac-admin $ENV initenv --config=config.ini
  $ cat config.ini
  [components]
  tracopt.versioncontrol.* = enabled

  [repositories]
  .dir = /path/to/default/type/repos
  repos1.type = git
  repos1.dir = /path/to/git/repos
  repos2.type = svn
  repos2.dir = /path/to/svn/repos
  }}}

  == Directory Structure

  An environment consists of the following files and directories:

   * `README` - Brief description of the environment.
   * `VERSION` - Environment version identifier.
   * `files`
    * `attachments` - Attachments to wiki pages and tickets.
   * `conf`
    * `trac.ini` - Main [TracIni configuration file].
   * `db`
    * `trac.db` - The SQLite database, if you are using SQLite.
   * `htdocs` - Directory containing web resources, which can be referenced in templates using the path `/chrome/site/...`.
   * `log` - Default directory for log files when `file` logging is enabled and a relative path is given.
   * `plugins` - Environment-specific [wiki:TracPlugins plugins].
   * `templates` - Custom Genshi environment-specific templates.
    * `site.html` - Method to [TracInterfaceCustomization#SiteAppearance customize] the site header, footer, and style.

  ----
  See also: TracAdmin, TracBackup, TracIni


name: TracFastCgi
author: trac
text:
  = Trac with FastCGI

  [[TracGuideToc]]
  [[PageOutline(2-5, Contents, floated)]]

  [https://fastcgi-archives.github.io FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request. Additionally, it is supported by a much wider variety of web servers.

  Note that unlike mod_python, FastCGI supports [https://httpd.apache.org/docs/suexec.html Apache SuEXEC], ie run with different permissions than the web server runs with. `mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect.

  '''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].

  == Apache configuration

  There are two FastCGI modules commonly available for Apache: `mod_fastcgi` and `mod_fcgid` (preferred). The latter is more up-to-date.

  The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.

  Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done: `Connection reset by peer: mod_fcgid: error reading data from FastCGI server`.

  === Set up with `mod_fastcgi`

  `mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
  {{{#!apache
  # Enable fastcgi for .fcgi files
  # (If you're using a distro package for mod_fcgi, something like
  # this is probably already present)
  <IfModule mod_fastcgi.c>
     AddHandler fastcgi-script .fcgi
     FastCgiIpcDir /var/lib/apache2/fastcgi
  </IfModule>
  LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
  }}}

  Setting `FastCgiIpcDir` is optional if the default is suitable. Note that the `LoadModule` line must be after the `IfModule` group.

  Configure `ScriptAlias` or similar options as described in TracCgi, but calling `trac.fcgi` instead of `trac.cgi`.

  Add the following to the Apache configuration file (below the `FastCgiIpcDir` line) if you intend to set up the `TRAC_ENV` as an overall default:
  {{{#!apache
  FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
  }}}

  Alternatively, you can serve multiple Trac projects in a directory by adding this:
  {{{#!apache
  FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
  }}}

  You can also specify the `PYTHON_EGG_CACHE` environment variable using a second `-initial-env` directive:
  {{{#!apache
  FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac \
      -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
  }}}

  === Set up with `mod_fcgid`

  Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` instead of `trac.cgi`:
  {{{#!apache
  ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/
  }}}

  Note the slash at the end.

  To set up Trac environment for `mod_fcgid` it is necessary to use `DefaultInitEnv` directive. It cannot be used in `Directory` or `Location` context, so if you need to support multiple projects, try the alternative environment setup below:
  {{{#!apache
  DefaultInitEnv TRAC_ENV /path/to/env/trac/
  }}}

  === Alternative environment setup

  A better method to specify the path to the Trac environment is to embed the path into `trac.fcgi` script itself. That doesn't require configuration of the server environment variables, works for both [trac:FastCgi] modules as well as for [https://www.lighttpd.net/ lighttpd] and CGI:
  {{{#!python
  import os
  os.environ['TRAC_ENV'] = "/path/to/projectenv"
  }}}

  or:
  {{{#!python
  import os
  os.environ['TRAC_ENV_PARENT_DIR'] = "/path/to/project/parent/dir"
  }}}

  With this method different projects can be supported by using different `.fcgi` scripts with different `ScriptAliases`.

  See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this:
  {{{#!apache
  ScriptAlias / /srv/tracsite/cgi-bin/trac.fcgi/
  }}}

  == Cherokee Configuration

  Configuring [http://cherokee-project.com/ Cherokee] with Trac is straightforward, if you spawn Trac as an SCGI process. You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down.

  First set up an information source in cherokee-admin with a local interpreter:

  {{{
  Host:
  localhost:4433

  Interpreter:
  /usr/bin/tracd —single-env —daemonize —protocol=scgi —hostname=localhost —port=4433 /path/to/project/
  }}}

  If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''.

  After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source.
  The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where $TRAC_LOCAL is a directory defined by the user or the system administrator to place local Trac resources).

  '''Note:''' If the tracd process fails to start up, and Cherokee displays a 503 error page, you might be missing the [https://www.saddi.com/software/flup/ python-flup] package ([trac:#9903]). Python-flup is a dependency which provides Trac with SCGI capability. You can install it on Debian based systems with:
  {{{#!sh
  sudo apt-get install python-flup
  }}}

  == Lighttpd Configuration

  The FastCGI front-end was developed primarily for use with alternative webservers, such as [https://www.lighttpd.net/ Lighttpd].

  Lighttpd is a secure, fast, compliant and very flexible web-server that has been optimized for high-performance environments. It has a very low memory footprint compared to other web servers and takes care of CPU load.

  For using `trac.fcgi`(prior to 0.11) / fcgi_frontend.py (0.11) with Lighttpd add the following to your lighttpd.conf:
  {{{
  #var.fcgi_binary="/usr/bin/python /path/to/fcgi_frontend.py" # 0.11 if installed with easy_setup, it is inside the egg directory
  var.fcgi_binary="/path/to/cgi-bin/trac.fcgi" # 0.10 name of prior fcgi executable
  fastcgi.server = ("/trac" =>

                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv")
                       )
                     )
                   )
  }}}

  Note that you will need to add a new entry to `fastcgi.server` for each separate Trac instance that you wish to run. Alternatively, you may use the `TRAC_ENV_PARENT_DIR` variable instead of `TRAC_ENV` as described above, and you may set one of the two in `trac.fcgi` instead of in `lighttpd.conf` using `bin-environment`, as in the section above on Apache configuration.

  Note that Lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This is fixed in Lighttpd 1.5, and under Lighttpd 1.4.23 or later the workaround is to add `"fix-root-scriptname" => "enable"` as a parameter of fastcgi.server.

  For using two projects with lighttpd add the following to your `lighttpd.conf`:
  {{{
  fastcgi.server = ("/first" =>
                     ("first" =>
                      ("socket" => "/tmp/trac-fastcgi-first.sock",
                       "bin-path" => fcgi_binary,
                       "check-local" => "disable",
                       "bin-environment" =>
                         ("TRAC_ENV" => "/path/to/projenv-first")
                      )
                    ),
                    "/second" =>
                      ("second" =>
                      ("socket" => "/tmp/trac-fastcgi-second.sock",
                       "bin-path" => fcgi_binary,
                       "check-local" => "disable",
                       "bin-environment" =>
                         ("TRAC_ENV" => "/path/to/projenv-second")
                      )
                    )
                  )
  }}}

  Note that the field values are different. If you prefer setting the environment variables in the `.fcgi` scripts, then copy/rename `trac.fcgi`, eg to `first.fcgi` and `second.fcgi`, and reference them in the above settings.
  Note that the above will result in different processes in any event, even if both are running from the same `trac.fcgi` script.

  {{{#!div class=important
  '''Note:''' The order in which the server.modules are loaded is very important: if mod_auth is not loaded '''before''' mod_fastcgi, then the server will fail to authenticate the user.
  }}}

  For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules:
  {{{
  server.modules              = (
  ...
    "mod_auth",
  ...
  )

  auth.backend               = "htpasswd"

  # Separated password files for each project
  # See "Conditional Configuration" in
  # https://redmine.lighttpd.net/projects/lighttpd/repository/entry/doc/configuration.txt?rev=lighttpd-1.4.28

  $HTTP["url"] =~ "^/first/" {
    auth.backend.htpasswd.userfile = "/path/to/projenv-first/htpasswd.htaccess"
  }
  $HTTP["url"] =~ "^/second/" {
    auth.backend.htpasswd.userfile = "/path/to/projenv-second/htpasswd.htaccess"
  }

  # Enable auth on trac URLs, see
  # https://redmine.lighttpd.net/projects/lighttpd/repository/entry/doc/authentication.txt?rev=lighttpd-1.4.28

  auth.require = ("/first/login" =>
                  ("method"  => "basic",
                   "realm"   => "First project",
                   "require" => "valid-user"
                  ),
                  "/second/login" =>
                  ("method"  => "basic",
                   "realm"   => "Second project",
                   "require" => "valid-user"
                  )
                 )

  }}}

  Note that Lighttpd (v1.4.3) stops if the password file doesn't exist.

  Note that Lighttpd doesn't support 'valid-user' in versions prior to 1.3.16.

  Conditional configuration is also useful for mapping static resources, ie serving out images and CSS directly instead of through FastCGI:
  {{{
  # Aliasing functionality is needed
  server.modules += ("mod_alias")

  # Set up an alias for the static resources
  alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs")

  # Use negative lookahead, matching all requests that ask for any resource under /trac, EXCEPT in
  # /trac/chrome/common, and use FastCGI for those
  $HTTP["url"] =~ "^/trac(?!/chrome/common)" {
  # Even if you have other fastcgi.server declarations for applications other than Trac, do NOT use += here
  fastcgi.server = ("/trac" =>
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv")
                       )
                     )
                   )
  }
  }}}

  The technique can be easily adapted for use with multiple projects by creating aliases for each of them, and wrapping the fastcgi.server declarations inside conditional configuration blocks.

  Also there is another way to handle multiple projects and it uses `TRAC_ENV_PARENT_DIR` instead of `TRAC_ENV` as well as global authentication:
  {{{
  #  This is for handling multiple projects
    alias.url       = ( "/trac/" => "/path/to/trac/htdocs/" )

    fastcgi.server += ("/projects"  =>
                        ("trac" =>
                          (
                            "socket" => "/tmp/trac.sock",
                            "bin-path" => fcgi_binary,
                            "check-local" => "disable",
                            "bin-environment" =>
                              ("TRAC_ENV_PARENT_DIR" => "/path/to/parent/dir/of/projects/" )
                          )
                        )
                      )
  #And here starts the global auth configuration
    auth.backend = "htpasswd"
    auth.backend.htpasswd.userfile = "/path/to/unique/htpassword/file/trac.htpasswd"
    $HTTP["url"] =~ "^/projects/.*/login$" {
      auth.require = ("/" =>
                       (
                         "method"  => "basic",
                         "realm"   => "trac",
                         "require" => "valid-user"
                       )
                     )
    }
  }}}

  Changing date/time format also supported by lighttpd over environment variable LC_TIME:
  {{{
  fastcgi.server = ("/trac" =>
                     ("trac" =>
                       ("socket" => "/tmp/trac-fastcgi.sock",
                        "bin-path" => fcgi_binary,
                        "check-local" => "disable",
                        "bin-environment" =>
                          ("TRAC_ENV" => "/path/to/projenv",
                          "LC_TIME" => "ru_RU")
                       )
                     )
                   )
  }}}

  For details about languages specification see [trac:TracFaq TracFaq] question 2.13.

  Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects.

  Relaunch Lighttpd and browse to `http://yourhost.example.org/trac` to access Trac.

  Note about running Lighttpd with reduced permissions: If nothing else helps and trac.fcgi doesn't start with Lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.

  == !LiteSpeed Configuration

  The FastCGI front-end was developed primarily for use with alternative webservers, such as [https://www.litespeedtech.com/ LiteSpeed].

  !LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.

   1. Please make sure you have a working install of a Trac project. Test install with "tracd" first.
   1. Create a Virtual Host for this setup. From now on we will refer to this vhost as !TracVhost. For this tutorial we will be assuming that your Trac project will be accessible via:
  {{{
  http://yourdomain.com/trac/
  }}}
   1. Go "!TracVhost → External Apps" tab and create a new "External Application":
  {{{
  Name: MyTracFCGI	
  Address: uds://tmp/lshttpd/mytracfcgi.sock
  Max Connections: 10
  Environment: TRAC_ENV=/fullpathto/mytracproject/ <--- path to root folder of trac project
  Initial Request Timeout (secs): 30
  Retry Timeout (secs): 0
  Persistent Connection	Yes
  Connection Keepalive Timeout: 30
  Response Bufferring: No	
  Auto Start: Yes
  Command: /usr/share/trac/cgi-bin/trac.fcgi  <--- path to trac.fcgi
  Back Log: 50
  Instances: 10
  }}}
   1. Optional: If you need to use htpasswd based authentication. Go to "!TracVhost → Security" tab and create a new security Realm:
   {{{
  DB Type: Password File
  Realm Name: MyTracUserDB               <--- any name you wish and referenced later
  User DB Location: /fullpathto/htpasswd <--- path to your htpasswd file
  }}}
   If you don’t have a htpasswd file or don’t know how to create the entries within one, go to http://sherylcanter.com/encrypt.php, to generate the user:password combos.
   1. Go to "!PythonVhost → Contexts" and create a new FCGI Context:
   {{{
  URI: /trac/                              <--- URI path to bind to python fcgi app we created	
  Fast CGI App: [VHost Level] MyTractFCGI  <--- select the Trac fcgi extapp we just created
  Realm: TracUserDB                        <--- only if (4) is set. select realm created in (4)
  }}}
   1. Modify `/fullpathto/mytracproject/conf/trac.ini`:
   {{{
  #find/set base_rul, url, and link variables
  base_url = http://yourdomain.com/trac/ <--- base url to generate correct links to
  url = http://yourdomain.com/trac/      <--- link of project
  link = http://yourdomain.com/trac/     <--- link of graphic logo
  }}}
   1. Restart !LiteSpeed: `lswsctrl restart`, and access your new Trac project at {{{http://yourdomain.com/trac/}}}.

  == Nginx Configuration

  [https://nginx.org/en/ Nginx] is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.

   1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
   {{{#!nginx
      server {
          listen       10.9.8.7:443;
          server_name  trac.example;

          ssl                  on;
          ssl_certificate      /etc/ssl/trac.example.crt;
          ssl_certificate_key  /etc/ssl/trac.example.key;

          ssl_session_timeout  5m;

          ssl_protocols  SSLv2 SSLv3 TLSv1;
          ssl_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
          ssl_prefer_server_ciphers   on;

          # it makes sense to serve static resources through Nginx (or ``~ [/some/prefix]/chrome/(.*)``)
          location ~ /chrome/(.*) {
               alias /home/trac/instance/static/htdocs/$1;
          }

          # You can copy this whole location to ``location [/some/prefix](/login)``
          # and remove the auth entries below if you want Trac to enforce
          # authorization where appropriate instead of needing to authenticate
          # for accessing the whole site.
          # (Or ``~ location /some/prefix(/.*)``.)
          location ~ (/.*) {
              auth_basic            "trac realm";
              auth_basic_user_file /home/trac/htpasswd;

              # socket address
              fastcgi_pass   unix:/home/trac/run/instance.sock;

              # python - wsgi specific
              fastcgi_param HTTPS on;

              ## WSGI REQUIRED VARIABLES
              # WSGI application name - trac instance prefix.
  	    # (Or ``fastcgi_param  SCRIPT_NAME  /some/prefix``.)
              fastcgi_param  SCRIPT_NAME        "";
              fastcgi_param  PATH_INFO          $1;

              ## WSGI NEEDED VARIABLES - trac warns about them
              fastcgi_param  REQUEST_METHOD     $request_method;
              fastcgi_param  SERVER_NAME        $server_name;
              fastcgi_param  SERVER_PORT        $server_port;
              fastcgi_param  SERVER_PROTOCOL    $server_protocol;
              fastcgi_param  QUERY_STRING       $query_string;

              # For Nginx authentication to work - do not forget to comment these
              # lines if not using Nginx for authentication
              fastcgi_param  AUTH_USER          $remote_user;
              fastcgi_param  REMOTE_USER        $remote_user;

              # for ip to work
              fastcgi_param REMOTE_ADDR         $remote_addr;

              # For attchments to work
              fastcgi_param    CONTENT_TYPE     $content_type;
              fastcgi_param    CONTENT_LENGTH   $content_length;
          }
      }
  }}}
   1. Modified trac.fcgi:
   {{{#!python
  #!/usr/bin/env python
  import os
  sockaddr = '/home/trac/run/instance.sock'
  os.environ['TRAC_ENV'] = '/home/trac/instance'

  try:
       from trac.web.main import dispatch_request
       import trac.web._fcgi

       fcgiserv = trac.web._fcgi.WSGIServer(dispatch_request,
            bindAddress = sockaddr, umask = 7)
       fcgiserv.run()

  except SystemExit:
      raise
  except Exception, e:
      print 'Content-Type: text/plain\r\n\r\n',
      print 'Oops...'
      print
      print 'Trac detected an internal error:'
      print
      print e
      print
      import traceback
      import StringIO
      tb = StringIO.StringIO()
      traceback.print_exc(file=tb)
      print tb.getvalue()

  }}}
   1. Reload nginx and launch trac.fcgi:
   {{{#!sh
  trac@trac.example ~ $ ./trac-standalone-fcgi.py
  }}}

  The above assumes that:
   * There is a user named 'trac' for running Trac instances and keeping Trac environments in its home directory
   * `/home/trac/instance` contains a Trac environment
   * `/home/trac/htpasswd` contains authentication information
   * `/home/trac/run` is owned by the same group the Nginx runs under
    * and if your system is Linux the `/home/trac/run` has setgid bit set (`chmod g+s run`)
    * and patch from [trac:#7239] is applied, or you'll have to fix the socket file permissions every time

  Unfortunately Nginx does not support variable expansion in fastcgi_pass directive.
  Thus it is not possible to serve multiple Trac instances from one server block.

  If you worry enough about security, run Trac instances under separate users.

  Another way to run Trac as a FCGI external application is offered in [trac:#6224].

  ----
  See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracCgi CGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]


name: TracFineGrainedPermissions
author: trac
text:
  = Fine grained permissions
  [[PageOutline(2-5, Contents, floated)]]
  [[TracGuideToc]]

  There is a general mechanism in place that allows custom **permission policies** to grant or deny any action on any Trac resource, or even specific versions of a resource.

  That mechanism is `AuthzPolicy`, an optional component in `tracopt.perm.authz_policy.*` which is not activated by default. It can be activated via the //Plugins// panel in the Trac administration module.

  See TracPermissions for a more general introduction to Trac permissions and permission policies.

  == Permission Policies

  A great diversity of permission policies can be implemented and Trac comes with a few examples.

  The active policies are determined by a [TracIni#trac-permission_policies-option configuration setting]:

  {{{#!ini
  [trac]
  permission_policies = DefaultWikiPolicy,
   DefaultTicketPolicy,
   DefaultPermissionPolicy,
   LegacyAttachmentPolicy
  }}}

  * [#DefaultWikiPolicyandDefaultTicketPolicy DefaultWikiPolicy] controls readonly access to wiki pages.
  * [#DefaultWikiPolicyandDefaultTicketPolicy DefaultTicketPolicy] provides elevated privileges in the ticket system for authenticated users.
  * !DefaultPermissionPolicy checks for the traditional coarse-grained permissions described in TracPermissions.
  * !LegacyAttachmentPolicy uses the coarse-grained permissions to check permissions on attachments.

  Among the optional choices, there is [#AuthzPolicy], a very generic permission policy, based on an Authz-style system. See
  [trac:source:branches/1.4-stable/tracopt/perm/authz_policy.py authz_policy.py] for details.

  Another permission policy [#AuthzSourcePolicy], uses the [http://svnbook.red-bean.com/nightly/en/svn.serverconfig.pathbasedauthz.html path-based authorization] defined by Subversion to enforce permissions on the version control system.

  See also [trac:source:branches/1.4-stable/sample-plugins/permissions sample-plugins/permissions] for more examples.

  === !AuthzPolicy
  ==== Configuration
  * Put an empty conf file (`authzpolicy.conf`) in a secure location on the server, not readable by users other than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
  * Update your `trac.ini`:
    1. modify the [TracIni#trac-permission_policies-option permission_policies] option in the `[trac]` section:
  {{{#!ini
  [trac]
  permission_policies = AuthzPolicy, DefaultWikiPolicy, DefaultTicketPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
  }}}
    1. add a new `[authz_policy]` section and point the `authz_file` option to the conf file:
  {{{#!ini
  [authz_policy]
  authz_file = /some/trac/env/conf/authzpolicy.conf
  }}}
    1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section:
  {{{#!ini
  [components]
  tracopt.perm.authz_policy.* = enabled
  }}}

  ==== Usage Notes

  Note the order in which permission policies are specified: policies are implemented in the sequence provided and therefore may override earlier policy specifications.

  A policy will return either `True`, `False` or `None` for a given permission check. `True` is returned if the policy explicitly grants the permission. `False` is returned if the policy explicitly denies the permission. `None` is returned if the policy is unable to either grant or deny the permission.

  NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted. If none of the policies explicitly grants the permission, the final result will be `False`, i.e. permission denied.

  The `authzpolicy.conf` file is a `.ini` style configuration file:
  {{{#!ini
  [wiki:PrivatePage@*]
  john = WIKI_VIEW, !WIKI_MODIFY
  jack = WIKI_VIEW
  * =
  }}}
  * Each section of the config is a glob pattern used to match against a Trac resource descriptor. These descriptors are in the form:
  {{{
  <realm>:<id>@<version>[/<realm>:<id>@<version> ...]
  }}}

  Resources are ordered left to right, from parent to child. If any component is inapplicable, `*` is substituted. If the version pattern is not specified explicitly, all versions (`@*`) is added implicitly. Example: Match the WikiStart page:
  {{{#!ini
  [wiki:*]
  [wiki:WikiStart*]
  [wiki:WikiStart@*]
  [wiki:WikiStart]
  }}}

  Example: Match the attachment `wiki:WikiStart@117/attachment:FOO.JPG@*` on WikiStart:
  {{{#!ini
  [wiki:*]
  [wiki:WikiStart*]
  [wiki:WikiStart@*]
  [wiki:WikiStart@*/attachment:*]
  [wiki:WikiStart@117/attachment:FOO.JPG]
  }}}

  * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of appearance in the configuration file. '''ORDER IS CRITICAL'''.

  * Once a section matches, the current username is matched against the keys (usernames) of the section, '''IN ORDER'''.
    * If a key (username) is prefixed with a `@`, it is treated as a group.
    * If a value (permission) is prefixed with a `!`, the permission is denied rather than granted.

  The username will match any of 'anonymous', 'authenticated', <username> or '*', using normal Trac permission rules.

  || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:#5648] for details about this missing feature. ||

  For example, if the `authz_file` contains:
  {{{#!ini
  [wiki:WikiStart@*]
  * = WIKI_VIEW

  [wiki:PrivatePage@*]
  john = WIKI_VIEW
  * = !WIKI_VIEW
  }}}
  and the default permissions are set like this:
  {{{
  john           WIKI_VIEW
  jack           WIKI_VIEW
  # anonymous has no WIKI_VIEW
  }}}

  Then:
    * All versions of WikiStart will be viewable by everybody, including anonymous
    * !PrivatePage will be viewable only by john
    * other pages will be viewable only by john and jack

  Groups:
  {{{#!ini
  [groups]
  admins = john, jack
  devs = alice, bob

  [wiki:Dev@*]
  @admins = TRAC_ADMIN
  @devs = WIKI_VIEW
  * =

  [*]
  @admins = TRAC_ADMIN
  * =
  }}}

  Then:
  - everything is blocked (whitelist approach), but
  - admins get all TRAC_ADMIN everywhere and
  - devs can view wiki pages.

  Some repository examples (Browse Source specific):
  {{{#!ini
  # A single repository:
  [repository:test_repo@*]
  john = BROWSER_VIEW, FILE_VIEW
  # John has BROWSER_VIEW and FILE_VIEW for the entire test_repo

  # The default repository (requires Trac 1.0.2 or later):
  [repository:@*]
  john = BROWSER_VIEW, FILE_VIEW
  # John has BROWSER_VIEW and FILE_VIEW for the entire default repository

  # All repositories:
  [repository:*@*]
  jack = BROWSER_VIEW, FILE_VIEW
  # Jack has BROWSER_VIEW and FILE_VIEW for all repositories
  }}}

  Very granular repository access:
  {{{#!ini
  # John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only
  [repository:test_repo@*/source:trunk/src/some/location/*@*]
  john = BROWSER_VIEW, FILE_VIEW

  # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only
  [repository:test_repo@*/source:trunk/src/some/location/*@1]
  john = BROWSER_VIEW, FILE_VIEW

  # John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only
  [repository:test_repo@*/source:trunk/src/some/location/somefile@*]
  john = BROWSER_VIEW, FILE_VIEW

  # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only
  [repository:test_repo@*/source:trunk/src/some/location/somefile@1]
  john = BROWSER_VIEW, FILE_VIEW
  }}}

  Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list.

  ==== Missing Features
  Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:#9573], [trac:#5648]). Patches are partially available, see authz_policy.2.patch, part of [trac:ticket:6680 #6680].

  You cannot do the following:
  {{{#!ini
  [groups]
  team1 = a, b, c
  team2 = d, e, f
  team3 = g, h, i
  departmentA = team1, team2
  }}}

  Permission groups are not supported either, so you cannot do the following:
  {{{#!ini
  [groups]
  permission_level_1 = WIKI_VIEW, TICKET_VIEW
  permission_level_2  = permission_level_1, WIKI_MODIFY, TICKET_MODIFY
  [*]
  @team1 = permission_level_1
  @team2 = permission_level_2
  @team3 = permission_level_2, TICKET_CREATE
  }}}

  === !AuthzSourcePolicy  (`mod_authz_svn`-like permission policy) #AuthzSourcePolicy

  `AuthzSourcePolicy` can be used for restricting access to the repository. Granular permission control needs a definition file, which is the one used by Subversion's `mod_authz_svn`.
  More information about this file format and about its usage in Subversion is available in the [http://svnbook.red-bean.com/en/1.7/svn.serverconfig.pathbasedauthz.html Path-Based Authorization] section in the Server Configuration chapter of the svn book.

  Example:
  {{{#!ini
  [/]
  * = r

  [/branches/calc/bug-142]
  harry = rw
  sally = r

  [/branches/calc/bug-142/secret]
  harry =
  }}}

   * '''/''' = ''Everyone has read access by default''
   * '''/branches/calc/bug-142''' = ''harry has read/write access, sally read only''
   * '''/branches/calc/bug-142/secret''' = ''harry has no access, sally has read access (inherited as a sub folder permission)''

  ==== Trac Configuration

  To activate granular permissions you __must__ specify the {{{authz_file}}} option in the `[svn]` section of trac.ini. If this option is set to null or not specified, the permissions will not be used.

  {{{#!ini
  [svn]
  authz_file = /path/to/svnaccessfile
  }}}

  If you want to support the use of the `[`''modulename''`:/`''some''`/`''path''`]` syntax within the `authz_file`, add:

  {{{#!ini
  authz_module_name = modulename
  }}}

  where ''modulename'' refers to the same repository indicated by the `<name>.dir` entry in the `[repositories]` section. As an example, if the `somemodule.dir` entry in the `[repositories]` section is `/srv/active/svn/somemodule`, that would yield the following:

  {{{ #!ini
  [svn]
  authz_file = /path/to/svnaccessfile
  authz_module_name = somemodule
  ...
  [repositories]
  somemodule.dir = /srv/active/svn/somemodule
  }}}

  where the svn access file, {{{/path/to/svnaccessfile}}}, contains entries such as {{{[somemodule:/some/path]}}}.

  '''Note:''' Usernames inside the Authz file __must__ be the same as those used inside trac.

  Make sure you have ''!AuthzSourcePolicy'' included in the permission_policies list in trac.ini, otherwise the authz permissions file will be ignored.

  {{{#!ini
  [trac]
  permission_policies = AuthzSourcePolicy, DefaultWikiPolicy, DefaultTicketPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
  }}}

  ==== Subversion Configuration

  The same access file is typically applied to the corresponding Subversion repository using an Apache directive like this:
  {{{#!apache
  <Location /repos>
    DAV svn
    SVNParentPath /usr/local/svn

    # our access control policy
    AuthzSVNAccessFile /path/to/svnaccessfile
  </Location>
  }}}

  For information about how to restrict access to entire projects in a multiple project environment see [trac:wiki:TracMultipleProjectsSVNAccess].

  === !DefaultWikiPolicy and !DefaultTicketPolicy

  Since 1.1.2, the read-only attribute of wiki pages is enabled and enforced when `DefaultWikiPolicy` is in the list of active permission policies (`DefaultWikiPolicy` was named `ReadonlyWikiPolicy` from Trac 1.1.2 to 1.3.1). The default for new Trac installations in 1.3.2 and later is:
  {{{#!ini
  [trac]
  permission_policies = DefaultWikiPolicy,
   DefaultTicketPolicy,
   DefaultPermissionPolicy,
   LegacyAttachmentPolicy
  }}}

  `DefaultWikiPolicy` returns `False` to deny modify, delete and rename actions on wiki pages when the page has the read-only attribute set and the user does not have `WIKI_ADMIN`, regardless of `WIKI_MODIFY`, `WIKI_DELETE` and `WIKI_RENAME` permissions. It returns `None` for all other cases, which causes the next permission policy in the list to be consulted.

  Since 1.3.2 `DefaultTicketPolicy` implements the following behaviors:
  * Authenticated user can edit their own comments.
  * Authenticated user with `TICKET_APPEND` or `TICKET_CHGPROP` can modify the description of a ticket they reported.
  * User with `MILESTONE_VIEW` can change  the ticket milestone.

  The wiki- and ticket-specific behaviors are implemented in permission policies so they can be easily replaced in case other behavior is desired.

  When upgrading from earlier versions of Trac, `DefaultWikiPolicy, DefaultTicketPolicy` will be appended to the list of `permission_policies` when upgrading the environment, provided that `permission_policies` has the default value (`ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy` if upgrading from Trac 1.1.2 or later). If any non-default `permission_polices` are active, `DefaultWikiPolicy, DefaultTicketPolicy` **will need to be manually added** to the list. A message will be echoed to the console when upgrading the environment, indicating if any action needs to be taken.

  **!DefaultWikiPolicy and !DefaultTicketPolicy must be listed //before// !DefaultPermissionPolicy**. The latter returns `True` to allow modify, delete or rename actions when the user has the respective `WIKI_*` permission, without consideration for the read-only attribute. Similarly, some of the behaviors implemented in `DefaultTicketPolicy` won't be considered if `DefaultPermissionPolicy` is executed first.

  When active, the [#AuthzPolicy] should therefore come before `DefaultWikiPolicy, DefaultTicketPolicy`, allowing it to grant or deny the actions on individual resources, which is the usual ordering for `AuthzPolicy` in the `permission_policies` list.
  {{{#!ini
  [trac]
  permission_policies = AuthzPolicy,
   DefaultWikiPolicy,
   DefaultTicketPolicy,
   DefaultPermissionPolicy,
   LegacyAttachmentPolicy
  }}}

  The placement of [#AuthzSourcePolicy] relative to `DefaultWikiPolicy, DefaultTicketPolicy` does not matter since they don't perform checks on the same realms.

  For all other permission policies, the user will need to decide the proper ordering. Generally, if the permission policy should be capable of overriding the checks performed by `DefaultWikiPolicy` or `DefaultTicketPolicy`, it should come before the policy it overrides. If `DefaultWikiPolicy` or `DefaultTicketPolicy` should override the check performed by another permission policy, as is the case for those policies relative to `DefaultPermissionPolicy`, then the overriding policy should come first.

  == Debugging permissions
  In trac.ini set:
  {{{#!ini
  [logging]
  log_file = trac.log
  log_level = DEBUG
  log_type = file
  }}}

  Display the trac.log to understand what checks are being performed:
  {{{#!sh
  tail -n 0 -f log/trac.log | egrep '\[perm\]|\[authz_policy\]'
  }}}

  See the sourced documentation of the plugin for more info.

  ----
  See also: TracPermissions,
  [https://trac-hacks.org/wiki/FineGrainedPageAuthzEditorPlugin FineGrainedPageAuthzEditorPlugin] for a simple editor.


name: TracGuide
author: trac
text:
  = The Trac User and Administration Guide

  [[TracGuideToc]]
  {{{#!span style="font-size:90%"
  //The TracGuide is meant to serve as a starting point for all documentation regarding Trac usage and development. The guide is a free document, a collaborative effort, and a part of the [trac: Trac Project] itself.//
  }}}

  == Introduction

  Trac is an enhanced wiki and issue tracking system for software development projects. Trac uses a minimalistic approach to web-based software project management. It helps developers write great software while staying out of the way. Trac should impose as little as possible on a team's established development process and policies.

  It provides an interface to Subversion as well as other version control systems, an integrated Wiki and convenient reporting facilities.

  Trac allows wiki markup in issue descriptions and commit messages, creating links and seamless references between bugs, tasks, changesets, files and wiki pages. A timeline shows all current and past project events in order, making the acquisition of an overview of the project and tracking progress very easy. The roadmap shows the road ahead, listing the upcoming milestones.

  == User Guide

     * Using the Wiki subsystem:
       * TracWiki — How to use the built-in Wiki.
       * WikiFormatting — Reference to the wiki syntax.
     * Using the Version Control subsystem:
       * TracBrowser — Browsing source code with Trac.
       * TracChangeset — Viewing changes to source code.
       * TracRevisionLog — Viewing change history.
     * Using the Ticket subsystem:
       * TracTickets — Using the issue tracker.
       * TracRoadmap — Tracking project progress.
       * TracReports — Writing and using reports.
       * TracQuery — Executing custom ticket queries.
       * TracBatchModify - Modifying several tickets in one request.
     * Other modules and general topics:
       * TracSearch — Full text search in all content.
       * TracTimeline — Historic perspective on a project.
       * TracRss — RSS content syndication.
       * TracAccessibility — Accessibility keys.

  == Administrator Guide

     * Installation and upgrade:
       * TracInstall — How to install and run Trac.
       * TracUpgrade — How to upgrade existing installations.
       * TracImport — Importing tickets from other bug databases.
       * TracPlugins — Installing and managing Trac extensions.
     * Configuration and customization:
       * TracIni — Trac configuration file reference.
       * TracPermissions — Access control and permissions.
       * TracNavigation — Customize main navigation menus.
       * TracInterfaceCustomization — Customizing the Trac interface.
       * TracLogging — The Trac logging facility.
     * Administering the Version Control subsystem:
       * TracRepositoryAdmin — Management of Source Code Repositories.
     * Administering the Ticket subsystem:
       * TracTicketsCustomFields — Expanding tickets with customized fields.
       * TracNotification — Email notification.
       * TracWorkflow — Configurable Ticket Workflow.
     * Reference:
       * TracEnvironment — All you need to know about Trac environments.
       * TracAdmin — Administering a Trac project via the command-line.

  == Support and Other Sources of Information

   * [trac:TracFaq Trac FAQ] — A collection of Frequently Asked Questions on the project website.
   * [trac:TracDev] and [trac:TracDev/ApiDocs API docs] — Trac Developer documentation.
   * TracSupport — How to get more information.

  If you are looking for a good place to ask a question about Trac, see the [trac:MailingList MailingList]. It provides a friendly environment to discuss openly among Trac users and developers.


name: TracImport
author: trac
text:
  = Importing ticket data

  [[PageOutline(2-5,Contents,pullout)]]

  To migrate issue tickets from other issue-tracking systems into Trac or perform housekeeping actions on tickets or simply synchronize different databases, there are some tools, plugins and scripts available.

  == !TicketImportPlugin

  [https://trac-hacks.org/wiki/TicketImportPlugin TicketImportPlugin]: a plugin that lets you import or update into Trac a series of tickets from a '''CSV file''' or (if the [https://pypi.python.org/pypi/xlrd xlrd library] is installed) from an '''Excel spreadsheet'''.

  == !ExportImportXlsPlugin

  [https://trac-hacks.org/wiki/ExportImportXlsPlugin ExportImportXlsPlugin]: a plugin that adds an admin panel for exporting and importing tickets via '''XLS file'''. Requires the python packages xlwt/rxld.

  == Jira

  [https://trac-hacks.org/wiki/JiraToTracIntegration JiraToTracIntegration]: a plugin that provides tools to import Atlassian Jira backup files into Trac. The plugin consists of a Python 3.1 commandline tool that:
   - Parses the Jira backup XML file.
   - Sends the imported Jira data and attachments to Trac using the [https://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin].
   - Generates a htpasswd file containing the imported Jira users and their SHA-512 base64 encoded passwords.

  == Mantis

  [https://trac-hacks.org/wiki/MantisImportScript MantisImportScript]: a script to import the following type of data from Mantis into Trac:
   * bugs
   * bug comments
   * bug activity (field changes)
   * attachments (as long as the files live in the mantis database, not on the filesystem).

  == !PlanetForge

  [https://trac-hacks.org/wiki/PlanetForgeImportExportPlugin PlanetForgeImportExportPlugin]: this plugin exports Trac data (wiki, tickets, compoments, permissions, repositories, etc.) using the open format designed by the [https://gforge.inria.fr/projects/coclico/ COCLICO] project. It extends the webadmin panel and the 'trac admin ...' command. Has no 'import' feature.

  == Scarab

  [https://trac-hacks.org/wiki/ScarabToTracScript ScarabToTracScript]: a script that migrates Scarab issues to Trac tickets. Requires [https://trac-hacks.org/wiki/XmlRpcPlugin XmlRpcPlugin].

  == Other

  Since Trac uses a SQL database to store the data, you can also custom-import from other systems by examining the database tables. Just go into [https://www.sqlite.org/sqlite.html sqlite] command line to look at the tables and import them from your application.

  ----
  See also:
   * to import/export wiki pages: TracAdmin,
   * to export tickets: TracTickets, TracQuery


name: TracIni
author: trac
text:
  = The Trac Configuration File

  [[TracGuideToc]]
  [[PageOutline(2-5,Contents,pullout)]]

  Trac is configured through the **`trac.ini`** file, located in the `<projectenv>/conf` directory. The `trac.ini` configuration file and its parent directory should be writable by the web server.

  Trac monitors the timestamp of the file to trigger an environment reload when the timestamp changes. Most changes to the configuration will be reflected immediately, though changes to the `[components]` or `[logging]` sections will require restarting the web server. You may also need to restart the web server after creating a [#GlobalConfiguration global configuration] file when none was previously present.

  == Global Configuration

  Configuration can be shared among environments using one or more global configuration files. Options in the global configuration will be merged with the environment-specific options, with local options overriding global options. The global configuration file is specified as follows:
  {{{#!ini
  [inherit]
  file = /path/to/global/trac.ini
  }}}
  Multiple files can be specified using a comma-separated list. Non-absolute paths are relative to the Environment `conf` directory.

  Note that you can also specify a global option file when creating a new project, by adding the option `--inherit=/path/to/global/trac.ini` to [TracAdmin#initenv trac-admin]'s `initenv` command. If you specify `--inherit` but nevertheless intend to use a global option file with your new environment, you will have to go through the newly generated `conf/trac.ini` file and delete the entries that will otherwise override those in the global file.

  There are three more options in the [#inherit-section "[inherit]"] section, [#inherit-templates_dir-option templates_dir] for sharing global templates, [#inherit-htdocs_dir-option htdocs_dir] for sharing global htdocs and [TracIni#inherit-plugins_dir-option plugins_dir], for sharing plugins. Those options can be specified in the shared configuration file, and in fact, configuration files can even be chained if you specify another `[inherit] file` there.

  Note that the templates found in the `templates/` directory of the TracEnvironment have precedence over those found in `[inherit] templates_dir`. In turn, the latter have precedence over the installed templates, so be careful about what you put there. Notably, if you override a default template, refresh your modifications when you upgrade to a new version of Trac. The preferred way to perform TracInterfaceCustomization is to write a custom plugin doing an appropriate `ITemplateStreamFilter` transformation.

  == Reference for settings

  This is a reference of available configuration options, and their default settings.

  Documentation improvements should be discussed on the [trac:MailingList#Trac-dev trac-dev mailing list] or described in a [trac:NewTicket ticket]. Even better, [trac:TracDev/SubmittingPatches submit a patch] against the docstrings in the code.

  [[TracIni]]

  == Configure Error Reporting

  The error reporting page has a //Create// button for reporting
  issues. The site to which issues are reported depends on the
  configuration of the Trac site and the user’s permissions.

  If the user doesn’t possess TRAC_ADMIN, the site to which a user is directed to create a ticket is determined by the [[#project-admin_trac_url-option|"[trac] admin_trac_url"]] setting:

  * If empty, there will be no //Create// button.
  * If set to the default value (`.`), the ticket will be
    created on the site which the error occurred.
  * Otherwise the ticket will be created at the site pointed
    to by `admin_trac_url`.

  If [[#project-admin-option|"[project] admin"]] is not empty, the administrator's email address will be rendered on the error page.

  If the user possesses TRAC_ADMIN, the //Create// button will direct the user to report the issue on trac.edgewall.org. If the error was generated in a plugin, the error will be reported to the project URL provided that the plugin author has included the project URL in the plugin installation data. The user possessing TRAC_ADMIN also sees a traceback and system information on the error page.

  ----
  See also: TracAdmin, TracEnvironment


name: TracInstall
author: trac
text:
  = Trac Installation Guide for 1.5
  [[TracGuideToc]]

  Trac is written in the Python programming language and needs a database, [https://sqlite.org/ SQLite], [https://www.postgresql.org/ PostgreSQL], or [https://mysql.com/ MySQL]. For HTML rendering, Trac uses the [http://jinja.pocoo.org Jinja2] templating system, though Genshi templates are supported until Trac 1.5.1.

  Trac can also be localized, and there is probably a translation available in your language. If you want to use the Trac interface in other languages, then make sure you have installed the optional package [#OtherPythonPackages Babel]. Pay attention to the extra steps for localization support in the [#InstallingTrac Installing Trac] section below. Lacking Babel, you will only get the default English version.

  If you're interested in contributing new translations for other languages or enhancing the existing translations, please have a look at [trac:wiki:TracL10N TracL10N].

  What follows are generic instructions for installing and setting up Trac. While you may find instructions for installing Trac on specific systems at [trac:TracInstallPlatforms TracInstallPlatforms], please '''first read through these general instructions''' to get a good understanding of the tasks involved.

  [[PageOutline(2-3,Installation Steps,inline)]]

  == Dependencies
  === Mandatory Dependencies
  To install Trac, the following software packages must be installed:

   * [https://www.python.org/ Python], version >= 3.5
   * [https://pypi.org/project/setuptools setuptools], version > 5.6
   * [https://pypi.org/project/Jinja2 Jinja2], version >= 2.9.3

  You also need a database system and the corresponding python bindings. The database can be either SQLite, PostgreSQL or MySQL.

  ==== For the SQLite database #ForSQLite

  You already have the SQLite database bindings bundled with the standard distribution of Python (the `sqlite3` module).

  Optionally, you may install a newer version of [https://pypi.org/project/pysqlite pysqlite] than the one provided by the Python distribution. See [trac:PySqlite#ThePysqlite2bindings PySqlite] for details.

  ==== For the PostgreSQL database #ForPostgreSQL

  You need to install the database and its Python bindings:
   * [https://www.postgresql.org/ PostgreSQL], version 9.1 or later
   * [https://pypi.org/project/psycopg2 psycopg2], version 2.5 or later

  See [trac:DatabaseBackend#Postgresql DatabaseBackend] for details.

  ==== For the MySQL database #ForMySQL

  Trac works well with MySQL, provided you use the following:

   * [https://mysql.com/ MySQL], version 5.0 or later
   * [https://pypi.org/project/PyMySQL PyMySQL]

  Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database.

  === Optional Dependencies

  ==== Subversion

  [https://subversion.apache.org/ Subversion], 1.14.x or later and the '''''corresponding''''' Python bindings.

  There are [https://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. See [trac:TracSubversion#GettingSubversion getting Subversion] for more information.

  {{{#!div style="border: 1pt dotted; margin: 1em"
  **Note:**
  * Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], nor does it work yet with the newer `ctype`-style bindings.
  * If using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are [trac:ticket:493 not supported].
  }}}

  For troubleshooting information, see the [trac:TracSubversion#Troubleshooting TracSubversion] page.

  ==== Git

  [https://git-scm.com/ Git] 1.5.6 or later is supported. More information is available on the [trac:TracGit] page.

  ==== Other Version Control Systems

  Support for other version control systems is provided via third-party plugins. See [trac:PluginList#VersionControlSystems] and [trac:VersionControlSystem].

  ==== Web Server
  A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.

  Alternatively you can configure Trac to run in any of the following environments:
   * [https://httpd.apache.org/ Apache] with
     - [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi], see [wiki:TracModWSGI] and
       [https://code.google.com/p/modwsgi/wiki/IntegrationWithTrac ModWSGI IntegrationWithTrac].
     - [http://modpython.org/ mod_python 3.5.0], see TracModPython
   * a [https://fastcgi-archives.github.io FastCGI]-capable web server (see TracFastCgi)
   * an [https://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html AJP]-capable web
     server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp])
   * Microsoft IIS with FastCGI and a FastCGI-to-WSGI gateway (see [trac:CookBook/Installation/TracOnWindowsIisWfastcgi IIS with FastCGI])
   * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script
     is highly discouraged''', better use one of the previous options.


  ==== Other Python Packages

   * [http://babel.pocoo.org Babel], version >= 2.2,
     needed for localization support
   * [http://pytz.sourceforge.net pytz] to get a complete list of time zones,
     otherwise Trac will fall back on a shorter list from
     an internal time zone implementation. Installing Babel
     will install pytz.
   * [http://docutils.sourceforge.net docutils],
     version >= 0.14, for WikiRestructuredText.
   * [http://pygments.org Pygments], version >= 1.0,
     for [TracSyntaxColoring syntax highlighting].
   * [https://pypi.org/project/textile Textile],
     version >= 2.3,
     for rendering the [https://github.com/textile/python-textile Textile markup language].
   * [https://pypi.org/project/passlib passlib] on Windows to decode [TracStandalone#BasicAuthorization:Usingahtpasswdpasswordfile htpasswd formats] other than `SHA-1`.
   * [https://pypi.org/project/pyreadline pyreadline] on Windows for trac-admin [TracAdmin#InteractiveMode command completion].

  {{{#!div style="border: 1pt dotted; margin: 1em"
  **Attention**: The available versions of these dependencies are not necessarily interchangeable, so please pay attention to the version numbers. If you are having trouble getting Trac to work, please double-check all the dependencies before asking for help on the [trac:MailingList] or [trac:IrcChannel].
  }}}

  Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''.

  == Installing Trac

  The [TracAdmin trac-admin] command-line tool, used to create and maintain [TracEnvironment project environments], as well as the [TracStandalone tracd] standalone server are installed along with Trac. There are several methods for installing Trac.

  It is assumed throughout this guide that you have elevated permissions as the `root` user or by prefixing commands with `sudo`. The umask `0002` should be used for a typical installation on a Unix-based platform.

  === Using `pip`
  `pip` is the modern Python package manager and is included in Python distributions. `pip` will automatically
  resolve the //required// dependencies (Jinja2 and
  setuptools) and download the latest packages from pypi.org.

  You can also install directly from a source package. You can obtain the source in a tar or zip from the [trac:TracDownload] page. After extracting the archive, change to the directory containing `setup.py` and run:

  {{{#!sh
  $ pip install .
  }}}

  `pip` supports numerous other install mechanisms. It can be passed the URL of an archive or other download location. Here are some examples:

  * Install the latest stable version from a zip archive:
  {{{#!sh
  $ pip install https://download.edgewall.org/trac/Trac-latest.zip
  }}}
  * Install the latest development version from a tar archive:
  {{{#!sh
  $ pip install https://download.edgewall.org/trac/Trac-latest-dev.tar.gz
  }}}
  * Install the unreleased 1.4-stable from subversion:
  {{{#!sh
  $ pip install svn+https://svn.edgewall.org/repos/trac/branches/1.2-stable
  }}}
  * Install the latest development preview (//not recommended for production installs//):
  {{{#!sh
  $ pip install --find-links=https://trac.edgewall.org/wiki/TracDownload Trac
  }}}

  The optional dependencies can be installed from PyPI using `pip`:
  {{{#!sh
  $ pip install babel docutils pygments textile
  }}}

  The optional dependencies can alternatively be
  specified using the `extras` keys in the setup file:
  {{{#!sh
  $ pip install Trac[babel,rest,pygments,textile]
  }}}

  `rest` is the extra that installs the `docutils`
  dependency.

  Include `mysql` or `psycopg2-binary` in the
  list if using the MySQL or PostgreSQL database.

  Additionally, you can install several Trac plugins from PyPI (listed [https://pypi.org/search/?c=Framework+%3A%3A+Trac here]) using pip. See TracPlugins for more information.

  === Using installer

  On Windows, Trac can be installed using the exe installers available on the [trac:TracDownload] page. Installers are available for the 32-bit and 64-bit versions of Python. Make sure to use the installer that matches the architecture of your Python installation.

  === Using package manager

  Trac may be available in your platform's package repository. However, your package manager may not provide the latest release of Trac.

  == Creating a Project Environment

  A [TracEnvironment Trac environment] is the backend where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is a directory that contains a human-readable [TracIni configuration file], and other files and directories.

  A new environment is created using [TracAdmin trac-admin]:
  {{{#!sh
  $ trac-admin /path/to/myproject initenv
  }}}

  [TracAdmin trac-admin] will prompt you for the information it needs to create the environment: the name of the project and the [TracEnvironment#DatabaseConnectionStrings database connection string]. If you're not sure what to specify for any of these options, just press `<Enter>` to use the default value.

  Using the default database connection string will always work as long as you have SQLite installed. For the other [trac:DatabaseBackend database backends] you should plan ahead and already have a database ready to use at this point.

  Also note that the values you specify here can be changed later using TracAdmin or directly editing the [TracIni conf/trac.ini] configuration file.

  Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter:
  {{{#!sh
  $ chown -R apache:apache /path/to/myproject
  }}}

  The actual username and groupname of the apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).

  {{{#!div class=important
  '''Warning:''' Please only use ASCII-characters for account name and project path, unicode characters are not supported there.
  }}}

  == Deploying Trac

  === Running the Standalone Server

  After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]:
  {{{#!sh
  $ tracd --port 8000 /path/to/myproject
  }}}

  Then, open a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that `tracd` knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this:
  {{{#!sh
  $ tracd -s --port 8000 /path/to/myproject
  }}}

  === Running Trac on a Web Server

  Trac provides various options for connecting to a "real" web server:
   - [TracFastCgi FastCGI]
   - [wiki:TracModWSGI Apache with mod_wsgi]
   - [TracModPython Apache with mod_python]
   - [TracCgi CGI] //(should not be used, as the performance is far from optimal)//

  Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [https://uwsgi-docs.readthedocs.io/en/latest/#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.

  ==== Generating the Trac cgi-bin directory #cgi-bin

  Application scripts for CGI, FastCGI and mod-wsgi can be generated using the [TracAdmin trac-admin] `deploy` command:
  [[TracAdminHelp(deploy)]]

  Grant the web server execution right on scripts in the `cgi-bin` directory.

  For example, the following yields a typical directory structure:
  {{{#!sh
  $ mkdir -p /var/trac
  $ trac-admin /var/trac/<project> initenv
  $ trac-admin /var/trac/<project> deploy /var/www
  $ ls /var/www
  cgi-bin	htdocs
  $ chmod ugo+x /var/www/cgi-bin/*
  }}}

  ==== Mapping Static Resources

  Without additional configuration, Trac will handle requests for static resources such as stylesheets and images. For anything other than a TracStandalone deployment, this is not optimal as the web server can be set up to directly serve the static resources. For CGI setup, this is '''highly undesirable''' as it causes abysmal performance.

  Web servers such as [https://httpd.apache.org/ Apache] allow you to create //Aliases// to resources, giving them a virtual URL that doesn't necessarily reflect their location on the file system. We can map requests for static resources directly to directories on the file system, to avoid Trac processing the requests.

  There are two primary URL paths for static resources: `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible at the `/chrome/<plugin>` path.

  A single `/chrome` alias can used if the static resources are extracted for all plugins. This means that the `deploy` command (discussed in the previous section) must be executed after installing or updating a plugin that provides static resources, or after modifying resources in the `$env/htdocs` directory. This is probably appropriate for most installations but may not be what you want if, for example, you wish to upload plugins through the //Plugins// administration page.

  The `deploy` command creates an `htdocs` directory with:
   - `common/` - the static resources of Trac
   - `site/` - a copy of the environment's `htdocs/` directory
   - `shared` - the static resources shared by multiple Trac environments, with a location defined by the `[inherit]` `htdocs_dir` option
   - `<plugin>/` - one directory for each resource directory provided by the plugins enabled for this environment

  The example that follows will create a single `/chrome` alias. If that isn't the correct approach for your installation you simply need to create more specific aliases:
  {{{#!apache
  Alias /trac/chrome/common /path/to/trac/htdocs/common
  Alias /trac/chrome/site /path/to/trac/htdocs/site
  Alias /trac/chrome/shared /path/to/trac/htdocs/shared
  Alias /trac/chrome/<plugin> /path/to/trac/htdocs/<plugin>
  }}}

  ===== Example: Apache and `ScriptAlias` #ScriptAlias-example

  Assuming the deployment has been done this way:
  {{{#!sh
  $ trac-admin /var/trac/<project> deploy /var/www
  }}}

  Add the following snippet to Apache configuration, changing paths to match your deployment. The snippet must be placed ''before'' the `ScriptAlias` or `WSGIScriptAlias` directive, because those directives map all requests to the Trac application:
  {{{#!apache
  Alias /trac/chrome /path/to/trac/htdocs

  <Directory "/path/to/www/trac/htdocs">
    # For Apache 2.2
    <IfModule !mod_authz_core.c>
      Order allow,deny
      Allow from all
    </IfModule>
    # For Apache 2.4
    <IfModule mod_authz_core.c>
      Require all granted
    </IfModule>
  </Directory>
  }}}

  If using mod_python, add this too, otherwise the alias will be ignored:
  {{{#!apache
  <Location "/trac/chrome/common">
    SetHandler None
  </Location>
  }}}

  Alternatively, if you wish to serve static resources directly from your project's `htdocs` directory rather than the location to which the files are extracted with the `deploy` command, you can configure Apache to serve those resources. Again, put this ''before'' the `ScriptAlias` or `WSGIScriptAlias` for the .*cgi scripts, and adjust names and locations to match your installation:
  {{{#!apache
  Alias /trac/chrome/site /path/to/projectenv/htdocs

  <Directory "/path/to/projectenv/htdocs">
    # For Apache 2.2
    <IfModule !mod_authz_core.c>
      Order allow,deny
      Allow from all
    </IfModule>
    # For Apache 2.4
    <IfModule mod_authz_core.c>
      Require all granted
    </IfModule>
  </Directory>
  }}}

  Another alternative to aliasing `/trac/chrome/common` is having Trac generate direct links for those static resources (and only those), using the [TracIni#trac-htdocs_location-option trac.htdocs_location] configuration setting:
  {{{#!ini
  [trac]
  htdocs_location = http://static.example.org/trac-common/
  }}}

  Note that this makes it easy to have a dedicated domain serve those static resources, preferentially cookie-less.

  Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
  {{{#!sh
  $ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
  }}}

  ==== Setting up the Plugin Cache

  Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the `PYTHON_EGG_CACHE` environment variable. Refer to your server documentation for detailed instructions on how to set environment variables.

  == Configuring Authentication

  Trac uses HTTP authentication. You'll need to configure your webserver to request authentication when the `.../login` URL is hit (the virtual path of the "login" button). Trac will automatically pick the `REMOTE_USER` variable up after you provide your credentials. Therefore, all user management goes through your web server configuration. Please consult the documentation of your web server for more info.

  The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac.

  Please refer to one of the following sections:
   * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
   * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi`, `mod_python`, `mod_fcgi` or `mod_fastcgi`.
   * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)

  [trac:TracAuthenticationIntroduction] also contains some useful information for beginners.

  == Granting admin rights to the admin user
  Grant admin rights to user admin:
  {{{#!sh
  $ trac-admin /path/to/myproject permission add admin TRAC_ADMIN
  }}}

  This user will have an //Admin// navigation item that directs to pages for administering your Trac project.

  == Configuring Trac

  Configuration options are documented on the TracIni page.

  TracRepositoryAdmin provides information on configuring version control repositories for your project.

  In addition to the optional version control backends, Trac provides several optional features that are disabled by default:
  * [TracFineGrainedPermissions#AuthzPolicy Fine-grained permission policy]
  * [TracPermissions#CreatingNewPrivileges Custom permissions]
  * [TracTickets#deleter Ticket deletion]
  * [TracTickets#cloner Ticket cloning]
  * [TracRepositoryAdmin#CommitTicketUpdater Ticket changeset references]

  == Using Trac

  Once you have your Trac site up and running, you should be able to create tickets, view the timeline, browse your version control repository if configured, etc.

  Keep in mind that //anonymous// (not logged in) users can by default access only a few of the features, in particular they will have a read-only access to the resources. You will need to configure authentication and grant additional [TracPermissions permissions] to authenticated users to see the full set of features.

  '' Enjoy! ''

  [trac:TracTeam The Trac Team]

  ----
  See also: [trac:TracInstallPlatforms TracInstallPlatforms], TracGuide, TracUpgrade


name: TracInterfaceCustomization
author: trac
text:
  = Customizing the Trac Interface
  [[TracGuideToc]]
  [[PageOutline(2-5,Contents,pullout)]]

  This page gives suggestions on how to customize the look of Trac. Topics include editing the HTML templates and CSS files, but not the program code itself. The topics show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.

  == Project Logo and Icon
  The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in [TracIni#project-section trac.ini].

  The logo or icon image should be put your environment's `htdocs` directory. You can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.

  Next, configure the appropriate section of your trac.ini:

  === Logo
  Change the `src` setting to `site/` followed by the name of your image file. The `width` and `height` settings should be modified to match your image's dimensions. The Trac chrome handler uses `site/` for files within the project directory `htdocs`, and `common/` for the common `htdocs` directory belonging to a Trac installation. Note that `site/` is not a placeholder for your project name, it is the literal prefix. For example, if your project is named `sandbox`, and the image file is `red_logo.gif` then the `src` setting would be `site/red_logo.gif`, not `sandbox/red_logo.gif`.

  {{{#!ini
  [header_logo]
  src = site/my_logo.gif
  alt = My Project
  width = 300
  height = 100
  }}}

  === Icon
  Icons are small images displayed by your web browser next to the site's URL and in the `Bookmarks` menu. Icons should be a 32x32 image in `.gif` or `.ico` format. Change the `icon` setting to `site/` followed by the name of your icon file:

  {{{#!ini
  [project]
  icon = site/my_icon.ico
  }}}

  == Custom Navigation Entries
  The `[mainnav]` and `[metanav]` sections of trac.ini be used to customize the navigation entries, disable them and even add new ones.

  In the following example, we:
  * rename the link to WikiStart to be //Home//
  * hide the ''About'' entry
  * make the //View Tickets// entry link to a specific report
  * add a //Builds// entry that links to an external build system
  * move the //Admin// entry to the meta navigation bar
  {{{#!ini
  [mainnav]
  wiki.label = Home
  tickets.href = /report/24

  [metanav]
  about = disabled
  builds = enabled
  builds.href = https://travis-ci.org/edgewall/trac
  admin = enabled
  }}}

  See also TracNavigation for a more detailed explanation of the mainnav and metanav navigation.

  == Site Appearance

  Trac is using [http://jinja.pocoo.org/ Jinja2] as the templating engine.

  We have put in place a number of "placeholder" in the form of "include" directives. These files don't need to exist, but if they do, their content will be processed by Jinja2 as well. As such, they can make use of other "include" directives, or any other feature of Jinja2 to generate dynamic content.

  There are three such placeholder templates:
   - `site_head.html`, which can be used to add content inside the generated `<head>` element
   - `site_header.html`, which can be used to **prepend** content inside the generated `<body>` element, before the standard content generated by Trac
   - `site_footer.html`, which can be used to **append** content inside the generated `<body>` element, after the standard content generated by Trac

  Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as `site_head.html`, `site_header.html` and `site_footer.html` inside your projects `templates/` directory (each Trac project can have their own "placeholder" files) e.g. `/path/to/env/templates/site_head.html`:

  `site_head.html`:
  {{{#!xml
    <!-- site_head.html: Add site-specific style sheet -->
    <link rel="stylesheet" href="${href.chrome('site/style.css')}" />
    <!-- /site_head.html -->
  }}}

  `site_header.html`:
  {{{#!xml
      <!-- site_header.html: Add site-specific header -->
      <div id="siteheader">
        ## Place your header content here...
      </div>
      <!-- /site_header.html -->
  }}}

  `site_footer.html`:
  {{{#!xml
      <!-- site_footer.html: Add site-specific footer -->
      <div id="sitefooter">
        ## Place your footer content here...
      </div>
      <!-- /site_footer.html -->
  }}}

  Notice that as Jinja2 is mostly content agnostic, you are free to open some `<div>` element in the `site_header.html` file and only close it in `site_footer.html` file.
  Besides, as in any other Trac Jinja2 template, you can use some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [TracIni#trac-htdocs_location-option "[trac] htdocs_location"] setting.

  Example snippet of adding introduction text to the new ticket form (but not shown during preview):

   - first we need to introduce the extra "content" of this notice, if it's appropriate for the request. For that, we add this snippet in the `site_footer.html` placeholder file:
    {{{#!xml
    # if req.path_info == '/newticket' and 'preview' not in req.args:
      <p id="ntg">Please make sure to search for existing tickets before reporting a new one!</p>
    # endif
    }}}
   - second, we need to dynamically alter the rest of the content in order to position that notice at the desired location. For that, we add this snippet to the `site_head.html` placeholder file:

  {{{#!xml
  <script>
    jQuery(function($) {
      var $ntg = $("#newticketguide");
      if ($ntg.length)
        $("#propertyform").prepend($ntg.detach());
    });
  </script>
  }}}

  This example illustrates a technique of using `req.path_info` to limit scope of changes to one view only. For instance, to make changes only for timeline and avoid modifying other sections, use `req.path_info == '/timeline'` as the condition in a `# if` test.

  More examples snippets for placeholder files can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].

  Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].

  === Sharing Templates in Multiple Environments

  The `site_*.html` templates, despite their name, can be put in a shared templates directory, see the [[TracIni#inherit-templates_dir-option|[inherit] templates_dir]] option. This could provide easier maintenance, as global `site_head.html`, `site_header.html` and `site_footer.html` files can be made to `# include` any other local existing header, footer and newticket snippets.

  == Project List #ProjectList

  You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects.

  The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded, it displays an error message. You can use this as a starting point for your own index template:

  FIXME

  {{{#!text/html
  <!DOCTYPE html
      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml"
        xmlns:py="http://genshi.edgewall.org/"
        xmlns:xi="http://www.w3.org/2001/XInclude">
    <head>
      <title>Available Projects</title>
    </head>
    <body>
      <h1>Available Projects</h1>
      <ul>
        <li py:for="project in projects" py:choose="">
          <a py:when="project.href" href="$project.href"
             title="$project.description">$project.name</a>
          <py:otherwise>
            <small>$project.name: <em>Error</em> <br /> ($project.description)</small>
          </py:otherwise>
        </li>
      </ul>
    </body>
  </html>
  }}}

  Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located:

  For [wiki:TracModWSGI mod_wsgi]:
  {{{#!python
  os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template.html'
  }}}

  For [TracFastCgi FastCGI]:
  {{{#!apache
  FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
                -initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
  }}}

  For [TracModPython mod_python]:
  {{{#!apache
  PythonOption TracEnvParentDir /parent/dir/of/projects
  PythonOption TracEnvIndexTemplate /path/to/template
  }}}

  For [TracCgi CGI]:
  {{{#!apache
  SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
  }}}

  For TracStandalone, you'll need to set up the `TRAC_ENV_INDEX_TEMPLATE` environment variable in the shell used to launch tracd:
   - Unix:
     {{{#!sh
  $ export TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     }}}
   - Windows:
     {{{#!sh
  $ set TRAC_ENV_INDEX_TEMPLATE=/path/to/template
     }}}

  == Project Templates

  The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use `site_{head,header,footer}.html` templates whenever possible, see [#SiteAppearance]. Using `site_{head,header,footer}.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version. If not, new Trac features or bug fixes may not work as expected.

  With that word of caution, any Trac template may be copied and customized. The default Trac templates are located in the Trac egg or wheel, such as `/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, ../trac/ticket/templates, ../trac/wiki/templates`. The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's or wheel's `trac/htdocs` directory.

  However, do not edit templates or site resources inside the Trac egg/wheel. Reinstalling Trac overwrites your modifications. Instead use one of these alternatives:
   * For a modification to one project only, copy the template to project `templates` directory.
   * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the [[TracIni#inherit-templates_dir-option|[inherit] templates_dir]] option.

  Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg or wheel.

  Trac caches templates in memory by default to improve performance. To apply a template you need to restart the web server.

  ----
  See also TracIni, TracNavigation


name: TracLinks
author: trac
text:
  = Trac Links

  [[TracGuideToc]]
  [[PageOutline(2-5,Contents,pullout)]]

  TracLinks are a fundamental feature of Trac, allowing easy hyperlinking between the various entities in the system — such as tickets, reports, changesets, Wiki pages, milestones, and source files — from anywhere WikiFormatting is used.

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

  == Where to use TracLinks

  You can use TracLinks 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.

  == Overview

  ||= Wiki Markup =||= Display =||
  {{{#!td
   Wiki pages :: `CamelCase` or `wiki:CamelCase`
   Parent page :: `[..]`
   Tickets :: `#1` or `ticket:1`
   Ticket comments :: `comment:1:ticket:2`
   Reports :: `{1}` or `report:1`
   Milestones :: `milestone:1.0`
   Attachment :: `attachment:example.tgz` (for current page attachment), `attachment:attachment.1073.diff:ticket:944` (absolute path)
   Changesets :: `r1`, `[1]`, `changeset:1` or (restricted) `[1/trunk]`, `changeset:1/trunk`, `[1/repository]`
   Revision log :: `r1:3`, `[1:3]` or `log:@1:3`, `log:trunk@1:3`, `[2:5/trunk]`
   Diffs :: `diff:@1:3`, `diff:plugins/0.12/mercurial-plugin@9128:9953`,
            `diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default`
            or `diff:trunk/trac@3538//sandbox/vc-refactoring@3539`
   Files :: `source:trunk/COPYING`, `source:/trunk/COPYING@200` (at version 200), `source:/trunk/COPYING@200#L25` (at version 200, line 25), `source:/trunk/COPYING@200:27-30#L25` (at version 200, line 25, highlighting lines 27-30)
  }}}
  {{{#!td
   Wiki pages :: CamelCase or wiki:CamelCase
   Parent page :: [..]
   Tickets :: #1 or ticket:1
   Ticket comments :: comment:1:ticket:2
   Reports :: {1} or report:1
   Milestones :: milestone:1.0
   Attachment :: attachment:example.tgz (for current page attachment), attachment:attachment.1073.diff:ticket:944 (absolute path)
   Changesets :: r1, [1], changeset:1 or (restricted) [1/trunk], changeset:1/trunk, [1/repository]
   Revision log :: r1:3, [1:3] or log:@1:3, log:trunk@1:3, [2:5/trunk]
   Diffs :: diff:@1:3, diff:plugins/0.12/mercurial-plugin@9128:9953,
            diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default
            or diff:trunk/trac@3538//sandbox/vc-refactoring@3539
   Files :: source:trunk/COPYING, source:/trunk/COPYING@200 (at version 200), source:/trunk/COPYING@200#L25 (at version 200, line 25) source:/trunk/COPYING@200:28-31#L25 (at version 200, line 25, highlighting lines 28-31)
  }}}

  '''Note:''' The wiki:CamelCase form is rarely used, but it can be convenient to refer to pages whose names do not follow WikiPageNames rules, ie single words, non-alphabetic characters, etc. See WikiPageNames for more about features specific to links to Wiki page names.


  {{{#!table class=""
  |||| Trac links using the full (non-shorthand) notation can also be given a custom link title like this: ||
  {{{#!td
  {{{
  [ticket:1 This is a link to ticket number one] or
  [[ticket:1|This is another link to ticket number one]].
  }}}
  }}}
  {{{#!td
  [ticket:1 This is a link to ticket number one] or
  [[ticket:1|This is another link to ticket number one]].
  }}}
  |--------------------------------------------------------------------------------------
  |||| If the title is omitted, only the id (the part after the colon) is displayed:  ||
  {{{#!td
  {{{
  [ticket:1] or [[ticket:2]]
  }}}
  }}}
  {{{#!td
  [ticket:1] or [[ticket:2]]
  }}}
  |--------------------------------------------------------------------------------------
  |||| `wiki` is the default if the namespace part of a full link is omitted:  ||
  {{{#!td
  {{{
  [SandBox the sandbox] or
  [[SandBox|the sandbox]]
  }}}
  }}}
  {{{#!td
  [SandBox the sandbox] or
  [[SandBox|the sandbox]]
  }}}
  |--------------------------------------------------------------------------------------
  |||| The short form ''realm:target'' can also be wrapped within a <...> pair, [[br]] which allow for arbitrary characters (i.e. anything but >)  ||
  {{{#!td
  {{{
  <wiki:Strange(page@!)>
  }}}
  }}}
  {{{#!td
  <wiki:Strange(page@!)>
  }}}
  |--------------------------------------------------------------------------------------
  |||| Quoting can be used with the full notation to allow brackets in the label. ||
  {{{#!td
  {{{
  [TracIni#logging-log_type-option "[logging] log_type"]
  }}}
  }}}
  {{{#!td
  [TracIni#logging-log_type-option "[logging] log_type"]
  }}}
  }}}

  TracLinks are a very simple idea, but actually allow 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.

  == Advanced use of TracLinks

  === Relative links

  To create a link to a [trac:SubWiki SubWiki]-page just use a '/':
  {{{
   WikiPage/SubWikiPage or ./SubWikiPage
  }}}

  To link from a [trac:SubWiki SubWiki] page to a parent, simply use a '..':
  {{{
    [..] or [[..]]
  }}}
    [..] or [[..]]

  To link from a [trac:SubWiki SubWiki] page to a [=#sibling sibling] page, use a '../':
  {{{
    [../Sibling see next sibling] or [[../Sibling|see next sibling]]
  }}}
    [../Sibling see next sibling] or [[../Sibling|see next sibling]]

  But in practice you often won't need to add the `../` prefix to link to a sibling page.
  For resolving the location of a wiki link, it's the target page closest in the hierarchy to the page where the link is written which will be selected. So for example, within a sub-hierarchy, a sibling page will be targeted in preference to a top-level page.
  This makes it easy to copy or move pages to a sub-hierarchy by [[WikiNewPage#renaming|renaming]] without having to adapt the links.

  To link explicitly to a [=#toplevel toplevel] Wiki page, use the `wiki:/` prefix. Be careful **not** to use the `/` prefix alone, as this corresponds to the [#Server-relativelinks] syntax and with such a link you will lack the `/wiki/` part in the resulting URL. A link such as `[../newticket]` will stay in the wiki namespace and therefore link to a sibling page.

  === Link anchors

  To create a link to a specific anchor in a page, use '#':
  {{{
   [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]
  }}}
    [#Linkanchors Link anchors] or [[#Linkanchors|Link anchors]]

  Hint: when you hover your mouse over the title of a section, a '¶' character will be displayed. This is a link to that specific section and you can use this to copy the `#...` part inside a relative link to an anchor.

  To create a link to the first or last occurrence of a term on a page, use a ''pseudo anchor'' starting with '#/' or '#?':
  {{{
   [#/Milestone first occurrence of Milestone] or
   [#?Milestone last occurrence of Milestone]
  }}}
   [#/Milestone first occurrence of Milestone] or
   [#?Milestone last occurrence of Milestone]
  This will also highlight all other matches on the linked page. By default only case sensitive matches are considered. To include case insensitive matches append '/i':
  {{{
   [#/Milestone/i first occurrence of Milestone or milestone] or
   [#?Milestone/i last occurrence of Milestone or milestone]
  }}}
   [#/Milestone/i first occurrence of Milestone or milestone] or
   [#?Milestone/i last occurrence of Milestone or milestone]

  ''(since Trac 1.0)''

  Such anchors can be very useful for linking to specific lines in a file in the source browser:
  {{{
   [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
   [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
  }}}
   [trac:source:tags/trac-0.12/trac/wiki/api.py#L127 Line 127] or
   [trac:source:tags/trac-0.12/trac/ticket/roadmap.py#L47 Line 47]
  (Hint: The line numbers displayed in the source browser are links to anchors on the respective lines.)

  Since such links become outdated when the file changes, it can be useful to link using a '#/' pseudo anchor instead:
  {{{
   [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
   [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]
  }}}
   [trac:source:trunk/trac/wiki/api.py#/IWikiSyntaxProvider IWikiSyntaxProvider] or
   [trac:source:trunk/trac/env.py#/ISystemInfoProvider ISystemInfoProvider]

  === InterWiki links

  Other prefixes can be defined freely and made to point to resources in other Web applications. The definition of those prefixes as well as the URLs of the corresponding Web applications is defined in a special Wiki page, the InterMapTxt page. Note that while this could be used to create links to other Trac environments, there is a more specialized way to register other Trac environments which offers greater flexibility.

  === InterTrac links

  This can be seen as a kind of InterWiki link specialized for targeting other Trac projects.

  Any type of Trac link can be written in one Trac environment and actually refer to resources in another Trac environment. All that is required is to prefix the Trac link with the name of the other Trac environment followed by a colon. The other Trac environment must be registered on the InterTrac page.

  A distinct advantage of InterTrac links over InterWiki links is that the shorthand form of Trac links can also be used, such as `{}`, `r`, `#`. For example, if T was set as an alias for Trac, then links to Trac tickets can be written as #T234, and links to Trac changesets can be written as [trac 1508].
  See InterTrac for the complete details.

  === Server-relative links

  It is often useful to be able to link to objects in your project that have no built-in Trac linking mechanism, such as static resources, `newticket`, a shared `/register` page on the server, etc.

  To link to resources inside the project, use either an absolute path from the project root, or a relative link from the URL of the current page (''Changed in 0.11''):

  {{{
  [/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
  [/ home] or [[/|home]]
  }}}

  Display: [/newticket Create a new ticket] or [[//newticket|Create a new ticket]]
  [/ home] or [[/|home]]

  To link to another location on the server (possibly outside the project but on the same host), use the `//` prefix (''Changed in 0.11''):

  {{{
  [//register Register Here] or [[//register|Register Here]]
  }}}

  Display: [//register Register Here] or [[//register|Register Here]]

  === Quoting space in TracLinks

  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:"the file.txt:ticket:123"

  Note that by using [trac:WikiCreole] style links, it's quite natural to write links containing spaces:
   * ![[The whitespace convention]]
   * ![[attachment:the file.txt]]

  === Escaping Links

  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.

  === Parameterized Trac links

  Many Trac resources have more than one way to be rendered, depending on some extra parameters. For example, a Wiki page can accept a `version` or a `format` parameter, a report can make use of dynamic variables, etc.

  Trac links can support an arbitrary set of parameters, written in the same way as they would be for the corresponding URL. Some examples:
   - `wiki:WikiStart?format=txt`
   - `ticket:1?version=1`
   - `[/newticket?component=module1 create a ticket for module1]`
   - `[/newticket?summary=Add+short+description+here create a ticket with URL with spaces]`

  == TracLinks Reference

  The following sections describe the individual link types in detail, as well as notes on advanced usage of links.

  === attachment: links

  The link syntax for attachments is as follows:
   * !attachment:the_file.txt creates a link to the attachment the_file.txt of the current page
   * !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

  Note that the older way, putting the filename at the end, is still supported: !attachment:ticket:753:the_file.txt, but is not recommended.

  If you'd like to create a direct link to the content of the attached file instead of a link to the attachment page, simply use `raw-attachment:` instead of `attachment:`.

  This can be useful for pointing directly to an HTML document, for example. Note that for this use case, you'd have to allow the web browser to render the content by setting [[TracIni#attachment-render_unsafe_content-option|"[attachment] render_unsafe_content"]] = `enabled`. Caveat: only do that in environments for which you're 100% confident you can trust the people who are able to attach files, as this opens up your site to [wikipedia:Cross-site_scripting cross-site scripting] attacks.

  See also [#export:links].

  === comment: links

  When you're inside a given ticket, you can simply write e.g. !comment:3 to link to the third change comment.
  It is possible to link to a comment of a specific ticket from anywhere using one of the following syntax:
   - `comment:3:ticket:123`
   - `ticket:123#comment:3` (note that you can't write `#123#!comment:3`!)
  It is also possible to link to the ticket's description using one of the following syntax:
   - `comment:description` (within the ticket)
   - `comment:description:ticket:123`
   - `ticket:123#comment:description`

  === htdocs: links

  Use `htdocs:path/to/file` to reference files in the `htdocs` directory of the Trac environment, the [TracEnvironment#DirectoryStructure web resource directory].

  === query: links

  See TracQuery#UsingTracLinks and [#ticket:links].

  === search: links

  See TracSearch#SearchTracLinks

  === ticket: links

   ''aliases:'' `bug:`, `issue:`

  Besides the obvious `ticket:id` form, it is also possible to specify a list of tickets or even a range of tickets instead of the `id`. This generates a link to a custom query view containing this fixed set of tickets.

  Example:
   - `ticket:5000-6000`
   - `ticket:1,150`

  === timeline: links

  Links to the timeline can be created by specifying a date in the ISO:8601 format. The date can be optionally followed by a time specification. The time is interpreted as being UTC time, but if you don't want to compute the UTC time, you can specify a local time followed by your timezone offset relative to UTC.

  Examples:
   - `timeline:2008-01-29`
   - `timeline:2008-01-29T15:48`
   - `timeline:2008-01-29T15:48Z`
   - `timeline:2008-01-29T16:48+01`
   - `timeline:2008-01-29T16:48+0100`
   - `timeline:2008-01-29T16:48+01:00`

  === wiki: links

  See WikiPageNames and [#QuotingspaceinTracLinks quoting space in TracLinks] above. It is possible to create a link to a specific page revision using the syntax WikiStart@1.

  === Version Control system links

  It should be noted that multiple repository support works by creating a kind of virtual namespace for versioned files in which the toplevel folders correspond to the repository names. Therefore, in presence of multiple repositories, a ''/path'' specification in the syntax of links detailed below should start with the name of the repository. If omitted, the default repository is used. In case a toplevel folder of the default repository has the same name as a repository, the link directs to the latter. One can always access such folder by fully qualifying it. The default repository can be an alias of a named repository, or conversely, there may be one or more aliases for the default repository, ask your Trac administrator.

  For example, `source:/trunk/COPYING` targets the path `/trunk/COPYING` in the default repository, whereas `source:/projectA/trunk/COPYING` targets the path `/trunk/COPYING` in the repository named `projectA`. This can be the same file if `'projectA'` is an alias to the default repository or if `''` (the default repository) is an alias to `'projectA'`.

  ==== source: links

   ''aliases:'' `browser:`, `repos:`

  The default behavior for a `source:/some/path link` is to open the browser in that directory directory if the path points to a directory or to show the latest content of the file.

  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
   - `source:/some/file@named-branch` - link to latest revision of the specified file in `named-branch` (DVCS such as Git or Mercurial)

  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`
   - `source:/some/file@named-branch#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, and target line 99
   - or without version number (the `@` is still needed): `source:/some/file@:10-20,100,103#L99`. Version can be omitted when the path is pointing to a source file that will no longer change (like `source:/tags/...`), otherwise it's better to specify which lines of //which version// of the file you're talking about.

  Note that in presence of multiple repositories, the name of the repository is simply integrated in the path you specify for `source:` (e.g. `source:reponame/trunk/README`). ''(since 0.12)''

  ==== export: links

  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
   * `export:/some/file@named-branch` - get latest revision of the specified file in `named-branch` (DVCS such as Git or Mercurial).

  This can be very useful for displaying XML or HTML documentation with correct stylesheets and images, in case that has been checked in into the repository. Note that for this use case, you'd have to allow the web browser to render the content by setting [[TracIni#browser-render_unsafe_content-option|"[browser] render_unsafe_content"]] = `enabled`, otherwise Trac will force the files to be downloaded as attachments for security concerns.

  If the path is to a directory in the repository instead of a specific file, the source browser will be used to display the directory (identical to the result of `source:/some/dir`).

  ==== log: links

  The `log:` links are used to display revision ranges. In its simplest form, it can link to the latest revisions of the specified path, but it can also support displaying an arbitrary set of revisions.
   - `log:/` - the latest revisions starting at the root of the repository
   - `log:/trunk/tools` - the latest revisions in `trunk/tools`
   - `log:/trunk/tools@10000` - the revisions in `trunk/tools` starting from  revision 10000
   - `log:@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795
   - `log:/trunk/tools@20788,20791:20795` - list revision 20788 and the revisions from 20791 to 20795 which affect the given path
   - `log:/tools@named-branch` - the revisions in `tools` starting from the latest revision in `named-branch` (DVCS such as Git or Mercurial)

  There are short forms for revision ranges as well:
   - `[20788,20791:20795]`
   - `[20788,20791:20795/trunk/tools]`
   - `r20791:20795` (but not `r20788,20791:20795` nor `r20791:20795/trunk`)

  Finally, note that in all of the above, a revision range can be written either as `x:y` or `x-y`.

  ==== Multi-repository links

  In the presence of multiple repositories, the name of the repository should be specified as the first part of the path:
  - `log:repos/branch`
  - `[20-40/repos]`
  - `r20/repos`

  ----
  See also: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki


name: TracLogging
author: trac
text:
  = Trac Logging
  [[TracGuideToc]]

  Trac supports logging of system messages using Python's [https://docs.python.org/2/library/logging.html logging module].

  Logging is configured in the [TracIni#logging-section "[logging]"] section of TracIni.

  == Supported Logging Methods

  The log method is set using the [TracIni#logging-log_type-option "[logging] log_type"] option, which accepts the following values:

   '''none'':: Suppress all log messages.
   '''file''':: Log messages to a file, specified with the [TracIni#logging-log_file-option "[logging] log_file"] option. Relative paths for `log_file` are resolved relative to the environment `log` directory.
   '''stderr''':: Output log entries to console ([TracStandalone tracd] only).
   '''syslog''':: (UNIX) Send log messages to the local syslogd via named pipe `/dev/log`. By default, syslog will write them to the `/var/log/messages` file.
   '''eventlog''':: (Windows) Use the system's NT Event Log.

  == Log Levels

  The verbosity level of logged messages can be set using the [TracIni#logging-log_level-option "[logging] log_level"] option. The log level defines the minimum level of urgency required for a message to be logged, and those levels are:

   '''CRITICAL''':: Log only the most critical (typically fatal) errors.
   '''ERROR''':: Log failures, bugs and errors.
   '''WARN''':: Log warnings, non-interrupting events.
   '''INFO''':: Diagnostic information, log information about all processing.
   '''DEBUG''':: Trace messages, profiling, etc.

  Additionally, you can  enable logging of SQL statements at debug level. This is turned off by default, as it's very verbose. Set [TracIni#trac-debug_sql-option "[trac] debug_sql  = yes"] to activate.

  == Log Format

  The output format for log entries can be specified in the [TracIni#logging-log_format-option "[logging] log_format"] option. The format is a string which can contain any of the [https://docs.python.org/2/library/logging.html#logrecord-attributes Python logging Formatter variables]. Additionally, the following Trac-specific variables can be used:
   '''$(basename)s''':: The environment directory name.
   '''$(path)s''':: The absolute path of the environment directory.
   '''$(project)s''':: The originating project's name.

  Note that variables are identified using a dollar sign (`$(...)s`) instead of percent sign (`%(...)s`).

  The default format is:
  {{{#!ini
  log_format = Trac[$(module)s] $(levelname)s: $(message)s
  }}}

  In a multi-project environment where all logs are sent to the same place (e.g. `syslog`), it makes sense to add the project name. In this example we use `basename` since that can generally be used to identify a project:
  {{{#!ini
  log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
  }}}

  ----
  See also: TracIni, TracEnvironment


name: TracModPython
author: trac
text:
  [[TracGuideToc]]

  = Trac and mod_python

  Mod_python is an [https://httpd.apache.org/ Apache] module that embeds the Python interpreter within the server, so that web-based applications in Python will run many times faster than traditional CGI and will have the ability to retain database connections.
  Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably, especially compared to [TracCgi CGI], and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.

  [[PageOutline(2-3,Overview,inline)]]

  == Simple configuration: single project #Simpleconfiguration

  If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
  {{{#!apache
  LoadModule python_module modules/mod_python.so
  }}}

  '''Note''': The exact path to the module depends on how the HTTPD installation is laid out.

  On Debian using apt-get:
  {{{#!sh
  apt-get install libapache2-mod-python libapache2-mod-python-doc
  }}}

  Still on Debian, after you have installed mod_python, you must enable the modules in apache2, equivalent to the above Load Module directive:
  {{{#!sh
  a2enmod python
  }}}

  On Fedora use, using yum:
  {{{#!sh
  yum install mod_python
  }}}

  You can test your mod_python installation by adding the following to your httpd.conf. You should remove this when you are done testing for security reasons. Note: mod_python.testhandler is only available in mod_python 3.2+.
  {{{#!apache
  <Location /mpinfo>
    SetHandler mod_python
    PythonInterpreter main_interpreter
    PythonHandler mod_python.testhandler
    # For Apache 2.2
    <IfModule !mod_authz_core.c>
      Order allow,deny
      Allow from all
    </IfModule>
    # For Apache 2.4
    <IfModule mod_authz_core.c>
      Require all granted
    </IfModule>
  </Location>
  }}}

  A simple setup of Trac on mod_python looks like this:
  {{{#!apache
  <Location /projects/myproject>
    SetHandler mod_python
    PythonInterpreter main_interpreter
    PythonHandler trac.web.modpython_frontend
    PythonOption TracEnv /var/trac/myproject
    PythonOption TracUriRoot /projects/myproject
    # For Apache 2.2
    <IfModule !mod_authz_core.c>
      Order allow,deny
      Allow from all
    </IfModule>
    # For Apache 2.4
    <IfModule mod_authz_core.c>
      Require all granted
    </IfModule>
  </Location>
  }}}

  The option '''`TracUriRoot`''' may or may not be necessary in your setup. Try your configuration without it; if the URLs produced by Trac look wrong, if Trac does not seem to recognize URLs correctly, or you get an odd "No handler matched request to..." error, add the '''`TracUriRoot`''' option. You will notice that the `Location` and '''`TracUriRoot`''' have the same path.

  The options available are:
  {{{#!apache
  # For a single project
  PythonOption TracEnv /var/trac/myproject

  # For multiple projects
  PythonOption TracEnvParentDir /var/trac/myprojects

  # For the index of multiple projects
  PythonOption TracEnvIndexTemplate /srv/www/htdocs/trac/project_list_template.html

  # A space delimitted list, with a "," between key and value pairs.
  PythonOption TracTemplateVars key1,val1 key2,val2

  # Useful to get the date in the wanted order
  PythonOption TracLocale en_GB.UTF8

  # See description above
  PythonOption TracUriRoot /projects/myproject
  }}}

  === Python Egg Cache

  Compressed Python eggs like Genshi are normally extracted into a directory named `.python-eggs` in the users home directory. Since Apache's home usually is not writeable, an alternate egg cache directory can be specified like this:
  {{{#!apache
  PythonOption PYTHON_EGG_CACHE /var/trac/myprojects/egg-cache
  }}}

  Or you can uncompress the Genshi egg to resolve problems extracting from it.

  === Configuring Authentication

  See corresponding section in the [wiki:TracModWSGI#ConfiguringAuthentication] page.

  == Advanced Configuration

  === Setting the Python Egg Cache

  If the Egg Cache isn't writeable by your Web server, you'll either have to change the permissions, or point Python to a location where Apache can write. This can manifest itself as a `500 internal server error` and/or a complaint in the syslog.

  {{{#!apache
  <Location /projects/myproject>
    ...
    PythonOption PYTHON_EGG_CACHE /tmp
    ...
  </Location>
  }}}

  === Setting the !PythonPath

  If the Trac installation isn't installed in your Python path, you will have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
  {{{#!apache
  <Location /projects/myproject>
    ...
    PythonPath "sys.path + ['/path/to/trac']"
    ...
  </Location>
  }}}

  Be careful about using the !PythonPath directive, and ''not'' `SetEnv PYTHONPATH`, as the latter won't work.

  === Setting up multiple projects

  The Trac mod_python handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
  {{{#!apache
  <Location /projects>
    SetHandler mod_python
    PythonInterpreter main_interpreter
    PythonHandler trac.web.modpython_frontend
    PythonOption TracEnvParentDir /var/trac
    PythonOption TracUriRoot /projects
  </Location>
  }}}

  When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir` that look like Trac environment directories. Selecting any project in the list will bring you to the corresponding Trac environment.

  Directories residing in `TracEnvParentDir` that are not environment directories will display an error message on the [TracInterfaceCustomization#ProjectList project index page]. The directories can be excluded by listing them in a `.tracignore` file residing in `TracEnvParentDir`. Unix [https://docs.python.org/2/library/fnmatch.html shell-style wildcard patterns] can be used in the newline separated list of directories.

  If you don't want to have the subdirectory listing as your projects home page you can use a
  {{{#!apache
  <LocationMatch "/.+/">
  }}}

  This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.

  You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
  {{{#!apache
  <LocationMatch "/projects/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /var/trac/.htpasswd
    Require valid-user
  </LocationMatch>
  }}}

  === Virtual Host Configuration

  Below is the sample configuration required to set up your Trac as a virtual server, ie when you access it at the URLs like
  `http://trac.mycompany.com`:

  {{{#!apache
  <VirtualHost *>
      DocumentRoot /var/www/myproject
      ServerName trac.mycompany.com
      <Location />
          SetHandler mod_python
          PythonInterpreter main_interpreter
          PythonHandler trac.web.modpython_frontend
          PythonOption TracEnv /var/trac/myproject
          PythonOption TracUriRoot /
      </Location>
      <Location /login>
          AuthType Basic
          AuthName "MyCompany Trac Server"
          AuthUserFile /var/trac/myproject/.htpasswd
          Require valid-user
      </Location>
  </VirtualHost>
  }}}

  This does not seem to work in all cases. What you can do if it does not:
   * Try using `<LocationMatch>` instead of `<Location>`.
   * `<Location />` may, in your server setup, refer to the complete host instead of simple the root of the server. This means that everything (including the login directory referenced below) will be sent to Python and authentication does not work, ie you get the infamous Authentication information missing error. If this is the case, try using a sub-directory for Trac instead of the root, ie /web/ and /web/login instead of / and /login.
   * Depending on apache's `NameVirtualHost` configuration, you may need to use `<VirtualHost *:80>` instead of `<VirtualHost *>`.

  For a virtual host that supports multiple projects replace `TracEnv /var/trac/myproject` with `TracEnvParentDir /var/trac`.

  '''Note''': !DocumentRoot should not point to your Trac project env. As Asmodai wrote on #trac: "suppose there's a webserver bug that allows disclosure of !DocumentRoot they could then leech the entire Trac environment".

  == Troubleshooting

  If you get server error pages, you can either check the Apache error log, or enable the `PythonDebug` option:
  {{{#!apache
  <Location /projects/myproject>
    ...
    PythonDebug on
  </Location>
  }}}

  For multiple projects, try restarting the server as well.

  === Login Not Working

  If you've used `<Location />` directive, it will override any other directives, as well as `<Location /login>`.
  The workaround is to use negation expression as follows (for multi project setups):
  {{{#!apache
  #this one for other pages
  <Location ~ "/*(?!login)">
     SetHandler mod_python
     PythonHandler trac.web.modpython_frontend
     PythonOption TracEnvParentDir /projects
     PythonOption TracUriRoot /
  </Location>

  #this one for login page
  <Location ~ "/[^/]+/login">
     SetHandler mod_python
     PythonHandler trac.web.modpython_frontend
     PythonOption TracEnvParentDir /projects
     PythonOption TracUriRoot /

     #remove these if you don't want to force SSL
     RewriteEngine On
     RewriteCond %{HTTPS} off
     RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

     AuthType Basic
     AuthName "Trac"
     AuthUserFile /projects/.htpasswd
     Require valid-user
  </Location>
  }}}

  === Expat-related segmentation faults === #expat

  This problem will most certainly hit you on Unix when using Python 2.4.
  In Python 2.4, some version of [http://expat.sourceforge.net/ Expat] (an XML parser library written in C) is used and if Apache is using another version, this results in segmentation faults.
  As Trac 0.11 is using Genshi, which will indirectly use Expat, that problem can now hit you even if everything was working fine before with Trac 0.10. This problem has not been reported for Python 2.5+, so best to upgrade.

  === Form submission problems

  If you're experiencing problems submitting some of the forms in Trac (a common problem is that you get redirected to the start page after submission), check whether your {{{DocumentRoot}}} contains a folder or file with the same path that you mapped the mod_python handler to. For some reason, mod_python gets confused when it is mapped to a location that also matches a static resource.

  === Problem with virtual host configuration

  If the <Location /> directive is used, setting the `DocumentRoot` may result in a ''403 (Forbidden)'' error. Either remove the `DocumentRoot` directive, or make sure that accessing the directory it points is allowed, in a corresponding `<Directory>` block.

  Using <Location /> together with `SetHandler` resulted in having everything handled by mod_python, which leads to not being able to download any CSS or images/icons. Use <Location /trac> `SetHandler None` </Location> to circumvent the problem, though this may not be the most elegant solution.

  === Problem with zipped egg

  It's possible that your version of mod_python will not import modules from zipped eggs. If you encounter an `ImportError: No module named trac` in your Apache logs but you think everything is where it should be, this might be your problem. Look in your site-packages directory; if the Trac module appears as a ''file'' rather than a ''directory'', then this might be your problem. To rectify this, try installing Trac using the `--always-unzip` option:

  {{{#!sh
  easy_install --always-unzip Trac-0.12b1.zip
  }}}

  === Using .htaccess

  Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.

  It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth.

  This also works out-of-box, with following trivial config:
  {{{#!apache
  SetHandler mod_python
  PythonInterpreter main_interpreter
  PythonHandler trac.web.modpython_frontend
  PythonOption TracEnv /system/path/to/this/directory
  PythonOption TracUriRoot /path/on/apache

  AuthType Basic
  AuthName "ProjectName"
  AuthUserFile /path/to/.htpasswd
  Require valid-user
  }}}

  The `TracUriRoot` is obviously the path you need to enter to the browser to get to Trac, eg `domain.tld/projects/trac`.

  === Additional .htaccess help

  If you are using the .htaccess method you may have additional problems if your Trac directory is inheriting .htaccess directives from another. This may also help to add to your .htaccess file:

  {{{#!apache
  <IfModule mod_rewrite.c>
    RewriteEngine Off
  </IfModule>
  }}}

  === Platform specific issues
  ==== Win32 Issues

  If you run Trac with mod_python < 3.2 on Windows, uploading attachments will '''not''' work. This problem is resolved in mod_python 3.1.4 or later, so please upgrade mod_python to fix this.

  ==== OS X issues

  When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, so please upgrade mod_python to fix this.

  ==== SELinux issues

  If Trac reports something like: `Cannot get shared lock on db.lock`, then the security context on the repository may need to be set:

  {{{#!sh
  chcon -R -h -t httpd_sys_content_t PATH_TO_REPOSITORY
  }}}

  See also [https://subversion.apache.org/faq.html#reposperms How do I set repository permissions correctly?]

  ==== FreeBSD issues

  The FreeBSD ports have both the new and old versions of mod_python and SQLite, but earlier versions of pysqlite and mod_python won't integrate:
   * pysqlite requires threaded support in Python
   * mod_python requires a threadless install.

  Apache2 does not automatically support threads on FreeBSD. You could force thread support when running `./configure` for Apache, using `--enable-threads`, but this isn´t recommended.
  The best option [http://modpython.org/pipermail/mod_python/2006-September/021983.html seems to be] adding to /usr/local/apache2/bin/ennvars the line:

  {{{#!sh
  export LD_PRELOAD=/usr/lib/libc_r.so
  }}}

  ==== Fedora 7 Issues

  Make sure you install the 'python-sqlite2' package as it seems to be required for TracModPython, but not for tracd.

  === Subversion issues

  If you get the following Trac error `Unsupported version control system "svn"` only under mod_python, though it works well on the command-line and even with TracStandalone, chances are that you forgot to add the path to the Python bindings with the [TracModPython#ConfiguringPythonPath PythonPath] directive. A better way is to add a link to the bindings in the Python `site-packages` directory, or create a `.pth` file in that directory.

  If this is not the case, it's possible that you are using Subversion libraries that are binary incompatible with the Apache ones and an incompatibility of the `apr` libraries is usually the cause. In that case, you also won't be able to use the svn modules for Apache (`mod_dav_svn`).

  You also need a recent version of `mod_python` in order to avoid a runtime error ({{{argument number 2: a 'apr_pool_t *' is expected}}}) due to the default usage of multiple sub-interpreters. Version 3.2.8 ''should'' work, though it's probably better to use the workaround described in [trac:#3371 #3371], in order to force the use of the main interpreter:
  {{{#!apache
  PythonInterpreter main_interpreter
  }}}

  This is also the recommended workaround for other issues seen when using the Python bindings for Subversion within mod_python ([trac:#2611 #2611], [trac:#3455 #3455]). See in particular Graham Dumpleton's comment in [trac:comment:9:ticket:3455 #3455] explaining the issue.

  === Page layout issues

  If the formatting of the Trac pages look weird, chances are that the style sheets governing the page layout are not handled properly by the web server. Try adding the following lines to your Apache configuration:
  {{{#!apache
  Alias /myproject/css "/usr/share/trac/htdocs/css"
  <Location /myproject/css>
      SetHandler None
  </Location>
  }}}

  '''Note''': For the above configuration to have any effect it must be put after the configuration of your project root location, ie {{{<Location /myproject />}}}.

  === HTTPS issues

  If you want to run Trac fully under https you might find that it tries to redirect to plain http. In this case just add the following line to your Apache configuration:
  {{{#!apache
  <VirtualHost *>
      DocumentRoot /var/www/myproject
      ServerName trac.mycompany.com
      SetEnv HTTPS 1
      ....
  </VirtualHost>
  }}}

  === Segmentation fault with php5-mhash or other php5 modules

  You may encounter segfaults (reported on Debian etch) if php5-mhash module is installed. Try to remove it to see if this solves the problem. See [https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=411487 Debian bug report].

  Some people also have troubles when using PHP5 compiled with its own third party libraries instead of system libraries. Check [https://www.djangoproject.com/documentation/modpython/#if-you-get-a-segmentation-fault Django segmentation fault].

  ----
  See also: TracGuide, TracInstall, [wiki:TracModWSGI ModWSGI], [wiki:TracFastCgi FastCGI], [trac:TracNginxRecipe]


name: TracModWSGI
author: trac
text:
  = Trac and mod_wsgi

  [https://github.com/GrahamDumpleton/mod_wsgi mod_wsgi] is an Apache module for running WSGI-compatible Python applications directly on top of the Apache webserver. The mod_wsgi adapter is written completely in C and provides very good performance.

  [[PageOutline(2-3,Overview,inline)]]

  == The `trac.wsgi` script

  Trac can be run on top of mod_wsgi with the help of an application script, which is a Python file saved with a `.wsgi` extension.

  A robust and generic version of this file can be created using the `trac-admin <env> deploy <dir>` command which automatically substitutes the required paths, see TracInstall#cgi-bin. The script should be sufficient for most installations and users not wanting more information can proceed to [#Mappingrequeststothescript configuring Apache].

  If you are using Trac with multiple projects, you can specify their common parent directory in `trac.wsgi`:
  {{{#!python
  def application(environ, start_request):
      # Add this when you have multiple projects
      environ.setdefault('trac.env_parent_dir', '/usr/share/trac/projects')
      ..
  }}}

  Directories residing in `trac.env_parent_dir` that are not environment directories will display an error message on the [TracInterfaceCustomization#ProjectList project index page]. The directories can be excluded by listing them in a `.tracignore` file residing in `trac.env_parent_dir`. Unix [https://docs.python.org/2/library/fnmatch.html shell-style wildcard patterns] can be used in the newline separated list of directories.

  === A very basic script

  In its simplest form, the script could be:

  {{{#!python
  import os

  os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  import trac.web.main
  application = trac.web.main.dispatch_request
  }}}

  The `TRAC_ENV` variable should naturally be the directory for your Trac environment, and the `PYTHON_EGG_CACHE` should be a directory where Python can temporarily extract Python eggs. If you have several Trac environments in a directory, you can also use `TRAC_ENV_PARENT_DIR` instead of `TRAC_ENV`.

  On Windows:
   - If run under the user's session, the Python Egg cache can be found in `%AppData%\Roaming`, for example:
  {{{#!python
  os.environ['PYTHON_EGG_CACHE'] = r'C:\Users\Administrator\AppData\Roaming\Python-Eggs'
  }}}
   - If run under a Window service, you should create a directory for Python Egg cache:
  {{{#!python
  os.environ['PYTHON_EGG_CACHE'] = r'C:\Trac-Python-Eggs'
  }}}

  === A more elaborate script

  If you are using multiple `.wsgi` files (for example one per Trac environment) you must ''not'' use `os.environ['TRAC_ENV']` to set the path to the Trac environment. Using this method may lead to Trac delivering the content of another Trac environment, as the variable may be filled with the path of a previously viewed Trac environment.

  To solve this problem, use the following `.wsgi` file instead:
  {{{#!python
  import os

  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  import trac.web.main
  def application(environ, start_response):
    environ['trac.env_path'] = '/usr/local/trac/mysite'
    return trac.web.main.dispatch_request(environ, start_response)
  }}}

  For clarity, you should give this file a `.wsgi` extension. You should probably put the file in its own directory, since you will expose it to Apache.

  If you have installed Trac and Python eggs in a path different from the standard one, you should add that path by adding the following code at the top of the wsgi script:

  {{{#!python
  import site
  site.addsitedir('/usr/local/trac/lib/python2.4/site-packages')
  }}}

  Change it according to the path you installed the Trac libs at.

  == Mapping requests to the script

  After preparing your .wsgi script, add the following to your Apache configuration file, typically `httpd.conf`:

  {{{#!apache
  WSGIScriptAlias /trac /usr/local/trac/mysite/apache/mysite.wsgi

  <Directory /usr/local/trac/mysite/apache>
      WSGIApplicationGroup %{GLOBAL}
      # For Apache 2.2
      <IfModule !mod_authz_core.c>
          Order deny,allow
          Allow from all
      </IfModule>
      # For Apache 2.4
      <IfModule mod_authz_core.c>
          Require all granted
      </IfModule>
  </Directory>
  }}}

  Here, the script is in a subdirectory of the Trac environment.

  If you followed the directions [TracInstall#cgi-bin Generating the Trac cgi-bin directory], your Apache configuration file should look like following:

  {{{#!apache
  WSGIScriptAlias /trac /usr/share/trac/cgi-bin/trac.wsgi

  <Directory /usr/share/trac/cgi-bin>
      WSGIApplicationGroup %{GLOBAL}
      # For Apache 2.2
      <IfModule !mod_authz_core.c>
          Order deny,allow
          Allow from all
      </IfModule>
      # For Apache 2.4
      <IfModule mod_authz_core.c>
          Require all granted
      </IfModule>
  </Directory>
  }}}

  In order to let Apache run the script, access to the directory in which the script resides is opened up to all of Apache. Additionally, the `WSGIApplicationGroup` directive ensures that Trac is always run in the first Python interpreter created by mod_wsgi. This is necessary because the Subversion Python bindings, which are used by Trac, don't always work in other sub-interpreters and may cause requests to hang or cause Apache to crash. After adding this configuration, restart Apache, and then it should work.

  To test the setup of Apache, mod_wsgi and Python itself (ie without involving Trac and dependencies), this simple wsgi application can be used to make sure that requests gets served (use as only content in your `.wsgi` script):

  {{{#!python
  def application(environ, start_response):
          start_response('200 OK',[('Content-type','text/html')])
          return ['<html><body>Hello World!</body></html>']
  }}}

  For more information about using the mod_wsgi specific directives, see the [https://code.google.com/archive/p/modwsgi/wikis mod_wsgi's wiki] and more specifically the [https://code.google.com/archive/p/modwsgi/wikis/IntegrationWithTrac.wiki IntegrationWithTrac] page.

  == Configuring Authentication

  The following sections describe different methods for setting up authentication. See also [https://httpd.apache.org/docs/2.4/howto/auth.html Authentication, Authorization and Access Control] in the Apache guide.

  === Using Basic Authentication

  The simplest way to enable authentication with Apache is to create a password file. Use the `htpasswd` program as follows:
  {{{#!sh
  $ htpasswd -c /somewhere/trac.htpasswd admin
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user admin
  }}}

  After the first user, you don't need the "-c" option anymore:
  {{{#!sh
  $ htpasswd /somewhere/trac.htpasswd john
  New password: <type password>
  Re-type new password: <type password again>
  Adding password for user john
  }}}

  See the man page for `htpasswd` for full documentation.

  After you've created the users, you can set their permissions using TracPermissions.

  Now, you need to enable authentication against the password file in the Apache configuration:
  {{{#!apache
  <Location "/trac/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </Location>
  }}}

  If you are hosting multiple projects, you can use the same password file for all of them:
  {{{#!apache
  <LocationMatch "/trac/[^/]+/login">
    AuthType Basic
    AuthName "Trac"
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </LocationMatch>
  }}}

  Note that neither a file nor a directory named 'login' needs to exist. See also the [https://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html mod_auth_basic] documentation.

  === Using Digest Authentication

  For better security, it is recommended that you either enable SSL or at least use the "digest" authentication scheme instead of "Basic".

  You have to create your `.htpasswd` file with the `htdigest` command instead of `htpasswd`, as follows:
  {{{#!sh
  $ htdigest -c /somewhere/trac.htpasswd trac admin
  }}}

  The "trac" parameter above is the "realm", and will have to be reused in the Apache configuration in the !AuthName directive:

  {{{#!apache
  <Location "/trac/login">
    AuthType Digest
    AuthName "trac"
    AuthDigestDomain /trac
    AuthUserFile /somewhere/trac.htpasswd
    Require valid-user
  </Location>
  }}}

  For multiple environments, you can use the same `LocationMatch` as described with the previous method.

  '''Note''': `Location` cannot be used inside .htaccess files, but must instead live within the main httpd.conf file. If you are on a shared server, you therefore will not be able to provide this level of granularity.

  Don't forget to activate the mod_auth_digest. For example, on a Debian 4.0r1 (etch) system:
  {{{#!apache
    LoadModule auth_digest_module /usr/lib/apache2/modules/mod_auth_digest.so
  }}}

  See also the [https://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html mod_auth_digest] documentation.

  === Using LDAP Authentication

  Configuration for [https://httpd.apache.org/docs/2.4/mod/mod_ldap.html mod_ldap] authentication in Apache is more involved (httpd 2.2+ and OpenLDAP: slapd 2.3.19).

  1. You need to load the following modules in Apache httpd.conf:
  {{{#!apache
    LoadModule ldap_module modules/mod_ldap.so
    LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
  }}}
  1. Your httpd.conf also needs to look something like:
  {{{#!apache
  <Location /trac/>
    # (if you're using it, mod_python specific settings go here)
    Order deny,allow
    Deny from all
    Allow from 192.168.11.0/24
    AuthType Basic
    AuthName "Trac"
    AuthBasicProvider "ldap"
    AuthLDAPURL "ldap://127.0.0.1/dc=example,dc=co,dc=ke?uid?sub?(objectClass=inetOrgPerson)"
    authzldapauthoritative Off
    Require valid-user
  </Location>
  }}}
  1. You can use the LDAP interface as a way to authenticate to a Microsoft Active Directory. Use the following as your LDAP URL:
  {{{#!apache
    AuthLDAPURL "ldap://directory.example.com:3268/DC=example,DC=com?sAMAccountName?sub?(objectClass=user)"
  }}}
   You will also need to provide an account for Apache to use when checking credentials. As this password will be listed in plain text in the configuration, you need to use an account specifically for this task:
  {{{#!apache
    AuthLDAPBindDN ldap-auth-user@example.com
    AuthLDAPBindPassword "password"
  }}}
   The whole section looks like:
  {{{#!apache
  <Location /trac/>
    # (if you're using it, mod_python specific settings go here)
    Order deny,allow
    Deny from all
    Allow from 192.168.11.0/24
    AuthType Basic
    AuthName "Trac"
    AuthBasicProvider "ldap"
    AuthLDAPURL "ldap://adserver.company.com:3268/DC=company,DC=com?sAMAccountName?sub?(objectClass=user)"
    AuthLDAPBindDN       ldap-auth-user@company.com
    AuthLDAPBindPassword "the_password"
    authzldapauthoritative Off
    # require valid-user
    Require ldap-group CN=Trac Users,CN=Users,DC=company,DC=com
  </Location>
  }}}

  Note 1: This is the case where the LDAP search will get around the multiple OUs, conecting to the Global Catalog Server portion of AD. Note the port is 3268, not the normal LDAP 389. The GCS is basically a "flattened" tree which allows searching for a user without knowing to which OU they belong.

  Note 2: You can also require the user be a member of a certain LDAP group, instead of just having a valid login:
  {{{#!apache
    Require ldap-group CN=Trac Users,CN=Users,DC=example,DC=com
  }}}

  See also:
   - [https://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html mod_authnz_ldap], documentation for mod_authnz_ldap.
   - [https://httpd.apache.org/docs/2.4/mod/mod_ldap.html mod_ldap], documentation for mod_ldap, which provides connection pooling and a shared cache.
   - [https://trac-hacks.org/wiki/LdapPlugin TracHacks:LdapPlugin] for storing TracPermissions in LDAP.

  === Using SSPI Authentication

  If you are using Apache on Windows, you can use mod_auth_sspi to provide single-sign-on. Download the module from the !SourceForge [https://sourceforge.net/projects/mod-auth-sspi/ mod-auth-sspi project] and then add the following to your !VirtualHost:
  {{{#!apache
  <Location /trac/login>
    AuthType SSPI
    AuthName "Trac Login"
    SSPIAuth On
    SSPIAuthoritative On
    SSPIDomain MyLocalDomain
    SSPIOfferBasic On
    SSPIOmitDomain Off
    SSPIBasicPreferred On
    Require valid-user
  </Location>
  }}}

  Using the above, usernames in Trac will be of the form `DOMAIN\username`, so you may have to re-add permissions and such. If you do not want the domain to be part of the username, set `SSPIOmitDomain On` instead.

  Some common problems with SSPI authentication: [trac:#1055], [trac:#1168] and [trac:#3338].

  See also [trac:TracOnWindows/Advanced].

  === Using CA !SiteMinder Authentication

  Setup CA !SiteMinder to protect your Trac login URL, for example `/trac/login`. Also, make sure the policy is set to include the HTTP_REMOTE_USER variable. If your site allows it, you can set this in `LocalConfig.conf`:
  {{{#!apache
  RemoteUserVar="WHATEVER_IT_SHOULD_BE"
  SetRemoteUser="YES"
  }}}

  The specific variable is site-dependent. Ask your site administrator. If your site does not allow the use of `LocalConfig.conf` for security reasons, have your site administrator set the policy on the server to set REMOTE_USER.

  Also add a !LogOffUri parameter to the agent configuration, for example `/trac/logout`.

  Then modify the trac.wsgi script generated using `trac-admin <env> deploy <dir>` to add the following lines, which extract the `HTTP_REMOTE_USER` variable and set it to `REMOTE_USER`:

  {{{#!python
  def application(environ, start_request):
      # Set authenticated username on CA SiteMinder to REMOTE_USER variable
      # strip() is used to remove any spaces on the end of the string
      if 'HTTP_SM_USER' in environ:
          environ['REMOTE_USER'] = environ['HTTP_REMOTE_USER'].strip()
      ...
  }}}

  You do not need any Apache "Location" directives.

  === Example: Apache/mod_wsgi with Basic Authentication, Trac being at the root of a virtual host

  Per the mod_wsgi documentation linked to above, here is an example Apache configuration that:
   - serves the Trac instance from a virtualhost subdomain
   - uses Apache basic authentication for Trac authentication.

  If you want your Trac to be served from eg !http://trac.my-proj.my-site.org, then from the folder eg `/home/trac-for-my-proj`, if you used the command `trac-admin the-env initenv` to create a folder `the-env`, and you used `trac-admin the-env deploy the-deploy` to create a folder `the-deploy`, then first:

  Create the htpasswd file:
  {{{#!sh
  cd /home/trac-for-my-proj/the-env
  htpasswd -c htpasswd firstuser
  ### and add more users to it as needed:
  htpasswd htpasswd seconduser
  }}}

  Keep the file above your document root for security reasons.

  Create this file for example `/etc/apache2/sites-enabled/trac.my-proj.my-site.org.conf` on Ubuntu with the following content:

  {{{#!apache
  <Directory /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi>
    WSGIApplicationGroup %{GLOBAL}
    Order deny,allow
    Allow from all
  </Directory>

  <VirtualHost *:80>
    ServerName trac.my-proj.my-site.org
    DocumentRoot /home/trac-for-my-proj/the-env/htdocs/
    WSGIScriptAlias / /home/trac-for-my-proj/the-deploy/cgi-bin/trac.wsgi
    <Location '/'>
      AuthType Basic
      AuthName "Trac"
      AuthUserFile /home/trac-for-my-proj/the-env/htpasswd
      Require valid-user
    </Location>
  </VirtualHost>

  }}}

  For subdomains to work you would probably also need to alter `/etc/hosts` and add A-Records to your host's DNS.

  == Troubleshooting

  === Use a recent version

  Please use either version 1.6, 2.4 or later of `mod_wsgi`. Versions prior to 2.4 in the 2.X branch have problems with some Apache configurations that use WSGI file wrapper extension. This extension is used in Trac to serve up attachments and static media files such as style sheets. If you are affected by this problem, attachments will appear to be empty and formatting of HTML pages will appear not to work due to style sheet files not loading properly. Another frequent symptom is that binary attachment downloads are truncated. See mod_wsgi tickets [https://code.google.com/archive/p/modwsgi/issues/100 #100] and [https://code.google.com/archive/p/modwsgi/issues/132 #132].

  '''Note''': using mod_wsgi 2.5 and Python 2.6.1 gave an Internal Server Error on my system (Apache 2.2.11 and Trac 0.11.2.1). Upgrading to Python 2.6.2 (as suggested [https://www.mail-archive.com/modwsgi@googlegroups.com/msg01917.html here]) solved this for me[[BR]]-- Graham Shanks

  If you plan to use `mod_wsgi` in embedded mode on Windows or with the MPM worker on Linux, then you will need version 3.4 or greater. See [trac:#10675] for details.

  === Getting Trac to work nicely with SSPI and 'Require Group'

  If you have set Trac up on Apache, Win32 and configured SSPI, but added a 'Require group' option to your Apache configuration, then the SSPIOmitDomain option is probably not working. If it is not working, your usernames in Trac probably look like 'DOMAIN\user' rather than 'user'.

  This WSGI script fixes that:
  {{{#!python
  import os
  import trac.web.main

  os.environ['TRAC_ENV'] = '/usr/local/trac/mysite'
  os.environ['PYTHON_EGG_CACHE'] = '/usr/local/trac/mysite/eggs'

  def application(environ, start_response):
      if "\\" in environ['REMOTE_USER']:
          environ['REMOTE_USER'] = environ['REMOTE_USER'].split("\\", 1)[1]
      return trac.web.main.dispatch_request(environ, start_response)
  }}}

  === Trac with PostgreSQL

  When using the mod_wsgi adapter with multiple Trac instances and PostgreSQL (or MySQL?) as the database, the server ''may'' create a lot of open database connections and thus PostgreSQL processes.

  A somewhat brutal workaround is to disable connection pooling in Trac. This is done by setting `poolable = False` in `trac.db.postgres_backend` on the `PostgreSQLConnection` class.

  But it is not necessary to edit the source of Trac. The following lines in `trac.wsgi` will also work:

  {{{#!python
  import trac.db.postgres_backend
  trac.db.postgres_backend.PostgreSQLConnection.poolable = False
  }}}

  or

  {{{#!python
  import trac.db.mysql_backend
  trac.db.mysql_backend.MySQLConnection.poolable = False
  }}}

  Now Trac drops the connection after serving a page and the connection count on the database will be kept low.

  //This is not a recommended approach though. See also the notes at the bottom of the [https://code.google.com/archive/p/modwsgi/wikis/IntegrationWithTrac.wiki mod_wsgi's IntegrationWithTrac] wiki page.//

  === Other resources

  For more troubleshooting tips, see also the [TracModPython#Troubleshooting mod_python troubleshooting] section, as most Apache-related issues are quite similar, plus discussion of potential [https://code.google.com/archive/p/modwsgi/wikis/ApplicationIssues.wiki application issues] when using mod_wsgi. The wsgi page also has a [https://code.google.com/archive/p/modwsgi/wikis/IntegrationWithTrac.wiki Integration With Trac] document.

  ----
  See also: TracGuide, TracInstall, [wiki:TracFastCgi FastCGI], [wiki:TracModPython ModPython], [trac:TracNginxRecipe TracNginxRecipe]


name: TracNavigation
author: trac
text:
  = Trac Navigation

  The main and meta navigation entries can be customized in several ways. The `[mainnav]` and `[metanav]` configuration sections can be used to customize the navigation item text and link, change the ordering of the navigation items, disable them and add new ones.

  The primary attributes that can be customized are `href`, `label`, `order` and `permission`.

  === `[mainnav]` #mainnav-bar
  `[mainnav]` corresponds to the '''main navigation bar''', the one containing entries such as ''Wiki'', ''Timeline'', ''Roadmap'', ''Browse Source'' and so on. This navigation bar is meant to access the default page of the main modules enabled in Trac that are accessible for the current user.


  ** [=#Example Example] **

  In the following example we rename the link to WikiStart //Home//, and make the //View Tickets// entry link to a specific report.
  {{{#!ini
  [mainnav]
  wiki.label = Home
  tickets.href = /report/24
  }}}

  Note the entries on the main navigation are displayed in uppercase regardless of the casing of the `label`, unless this aspect of the styling is overridden through [TracInterfaceCustomization#SiteAppearance interface customization].

  === `[metanav]` #metanav-bar
  `[metanav]` corresponds to the '''meta navigation bar''', by default positioned above the main navigation bar and below the ''Search'' box. It contains the ''Login'', ''Logout'', ''!Help/Guide'' etc. entries. This navigation bar is meant to access some global information about the Trac project and the current user.

  There is one special entry in the  `[metanav]` section: `logout.redirect` is the page the user sees after hitting the logout button.  The ''!Help/Guide'' link is also hidden in the following example.
  [[comment(see also #Trac3808)]]

  ** Example **

  {{{#!ini
  [metanav]
  help = disabled
  logout.redirect = wiki/Logout
  }}}

  === Extra Navigation Entries #nav-extra-entries

  New navigation entries can be arbitrarily defined and added
  to the navigation. A new entry can be defined by providing a name with value `enabled`. At a minimum, the `href` attribute should be specified to define a useful navigation entry. If the `label` attribute is not defined the entry's name will be used for the label.

  The following example creates two new navigation items, one named //My Reports// and the other named //builds//. //My Reports// is only visible to users with `REPORT_VIEW` permission.
  {{{#!ini
  [mainnav]
  myreports = enabled
  myreports.href = /report/9
  myreports.label = My Reports
  myreports.permission = REPORT_VIEW

  [metanav]
  builds = enabled
  builds.href = https://travis-ci.org/edgewall/trac
  }}}

  The entry names are always read as lowercase, as is the case for all keys in the trac.ini file due to the way the configuration parser is configured. If the example above used `BUILDS` rather than `builds` for the name, the entry would still be displayed as `builds`. Use the `label` attribute for case-sensitive customization of the navigation entry text.

  === Relocating Entries #nav-relocating-entries

  Navigation entries provided by Trac and plugins can be moved from the meta navigation bar to the main navigation bar, and vise-versa. The entry should be defined in the desired category as if it was a new entry. For example, to move the //Admin// entry to the metanav and rename it to //Administration//:
  {{{#!ini
  [metanav]
  admin = enabled
  admin.label = Administration
  }}}

  Attributes of the navigation item that are not overridden by the configuration will be preserved.

  === URL Formats
  Possible URL formats for `.href` or `.redirect`:
  || '''config''' || '''redirect to''' ||
  || `wiki/Logout` || `/projects/env/wiki/Logout` ||
  || `http://hostname/` || `http://hostname/` ||
  || `/projects` || `/projects` ||


  === Ordering #nav-order
  The `order` attribute specifies the order in which the navigation items are displayed. This can be particularly useful for plugins that add navigation items.

  Non-negative floating point values may be used for the `order` attribute. The navigation items will be arranged from left to right in increasing order. Navigation items without an `order` attribute are sorted alphabetically by name.

  The default values are:
  {{{#!ini
  [mainnav]
  browser.order = 4
  newticket.order = 6
  roadmap.order = 3
  search.order = 7
  tickets.order = 5
  timeline.order = 2
  wiki.order = 1

  [metanav]
  about.order = 5
  help.order = 4
  login.order = 1
  logout.order = 2
  prefs.order = 3
  }}}

  === Permissions #nav-permissions
  The `permission` attribute controls the visibility of the navigation item on the navigation bar. This is mainly useful for new entries in the navigation bar. Note that it does not provide access control to the URL that the navigation item directs to, and cannot override permission checks done by Trac and plugins.

  For example, the //Roadmap// navigation item will only display for users with `ROADMAP_VIEW`. Adding the attribute `roadmap.permission = MILESTONE_VIEW` will require both `ROADMAP_VIEW` and `MILESTONE_VIEW` for the entry to be visible, but as noted will not provide access control for the `/roadmap` path. TracFineGrainedPermissions should be used for access control to modules provided by Trac and plugins.

  === Context Navigation #ctxtnav-bar

  Note that it is still not possible to customize the '''contextual navigation bar''', i.e. the one usually placed below the main navigation bar.

  ----
  See also: TracInterfaceCustomization


name: TracNotification
author: trac
text:
  = Email Notification of Ticket Changes
  [[TracGuideToc]]

  Trac supports notification of ticket changes via email.

  Email notification is useful to keep users up-to-date on tickets of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list.

  Disabled by default, notification can be activated and configured in [TracIni trac.ini].

  == Receiving Notification Mails
  When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac may send you an email when changes are made to the ticket, depending on how your notification preferences are configured.

  Permission groups can also be entered in the CC field,
  to notify all members of the group.

  === How to use your username to receive notification mails

  To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in your [/prefs preferences].

  Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation.

  When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''`username@EXAMPLE.LOCAL`'''). To avoid this being interpreted as an email address, add the Kerberos domain to  ('''`ignore_domains`''').

  === Ticket attachment notifications

  Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the `TicketAttachmentNotifier` component must be disabled:
  {{{#!ini
  [components]
  trac.ticket.notification.TicketAttachmentNotifier = disabled
  }}}

  == Configuring SMTP Notification

  '''Important:''' The [[TracIni#trac-base_url-option|[trac] base_url]] option must be configured for links in the notification message to be correctly generated.

  === Configuration Options
  These are the available options for the `[notification]` section in trac.ini:

  [[TracIni(section=notification)]]

  === Example Configuration (SMTP)
  {{{#!ini
  [notification]
  smtp_enabled = true
  smtp_server = mail.example.com
  smtp_from = notifier@example.com
  smtp_replyto = myproj@projects.example.com
  smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
  }}}

  === Example Configuration (`sendmail`)
  {{{#!ini
  [notification]
  smtp_enabled = true
  email_sender = SendmailEmailSender
  sendmail_path = /usr/sbin/sendmail
  smtp_from = notifier@example.com
  smtp_replyto = myproj@projects.example.com
  smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
  }}}

  === Subscriber Configuration
  The default subscriptions are configured in the [TracIni#notification-subscriber-section "[notification-subscriber]"] section.

  [[TracIni(section=notification-subscriber)]]

  Each user can override these defaults in their ''Notifications'' preferences.

  For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules.

  The subscription rule name on the left side of the `=` can be anything, it has no meaning outside this configuration file. The subscriber name on the right side of the `=` must be one of the subscribers listed in the above table.

  The following attributes of default subscriptions can be configured:
  * `.distributor` (Default: `email`)
    * Other values require plugins. For example `on-site` requires th:OnSiteNotificationsPlugin.
  * `.priority` (Default: `100`)
    * Smaller values override larger values.
    * If you use `0`, then users will not be able to override this rule.
  * `.adverb` (Default: `always`)
    * `never` can be used to silence other subscription rules with higher values.
  * `.format` (Default: `text/plain`)
    * Other values require plugins. For example `text/html` requires th:TracHtmlNotificationPlugin.

  === Example Configuration (default subscriptions)
  {{{#!ini
  [notification-subscriber]
  always_notify_owner = TicketOwnerSubscriber
  always_notify_owner.distributor = email
  always_notify_owner.priority = 100
  always_notify_owner.adverb = always
  always_notify_owner.format = text/plain

  always_notify_previous_updater = TicketPreviousUpdatersSubscriber

  never_notify_updater = TicketUpdaterSubscriber
  never_notify_updater.adverb = never
  never_notify_updater.priority = 0

  notify_cc_html = CarbonCopySubscriber
  notify_cc_html.format = text/html
  }}}

  === Customizing the email subject
  The email subject can be customized with the `ticket_subject_template` option, which contains a [https://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is:
  {{{#!genshi
  ${prefix} #${ticket.id}: ${summary}
  }}}
  The following variables are available in the template:

   * `changes`: The ticket changes (prepared by [trac:source:/branches/1.4-stable/trac/ticket/model.py Ticket.get_change]).
   * `env`: The project environment (see [trac:source:/branches/1.4-stable/trac/env.py env.py]).
   * `prefix`: The prefix defined in `smtp_subject_prefix`.
   * `summary`: The ticket summary, with the old value if the summary was edited.
   * `ticket`: The ticket model object (see [trac:source:/branches/1.4-stable/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg `${ticket.milestone}`.

  === Customizing the email content #CustomizingContent

  The notification email content is generated based on `ticket_notify_email.txt` in `trac/ticket/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default is:

  {{{#!jinja
  ${ticket_body_hdr}
  ${ticket_props}
  # if ticket.new:
  ${ticket.description}
  # else:
  #   if changes_body:
  ${_('Changes (by %(author)s):', author=change.author)}

  ${changes_body}
  #   endif
  #   if changes_descr:
  #     if not changes_body and not change.comment and change.author:
  ${_('Description changed by %(author)s:', author=change.author)}
  #     endif
  ${changes_descr}
  --
  #   endif
  #   if change.comment:

  ${_('Comment:') if changes_body else
    _('Comment (by %(author)s):', author=change.author)}

  ${change.comment}
  #   endif
  # endif
  ${'-- '}
  ${_('Ticket URL: <%(link)s>', link=ticket.link)}
  ${project.name} <${project.url or abs_href()}>
  ${project.descr}
  }}}

  See the [trac:CookBook/Notification/Templates cookbook] for additional template customization recipes.

  == Sample Email
  {{{
  #42: testing
  ---------------------------+------------------------------------------------
         Id:  42             |      Status:  assigned
  Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004
   Severity:  major          |   Milestone:  0.9
   Priority:  lowest         |     Version:  0.6
      Owner:  anonymous      |    Reporter:  jonas@example.com
  ---------------------------+------------------------------------------------
  Changes:
    * component:  changeset view => search system
    * priority:  low => highest
    * owner:  jonas => anonymous
    * cc:  daniel@example.com =>
           daniel@example.com, jonas@example.com
    * status:  new => assigned

  Comment:
  I'm interested too!

  --
  Ticket URL: <http://example.com/trac/ticket/42>
  My Project <http://myproj.example.com/>
  }}}

  == Using GMail as the SMTP relay host

  Use the following configuration snippet:
  {{{#!ini
  [notification]
  smtp_enabled = true
  use_tls = true
  mime_encoding = base64
  smtp_server = smtp.gmail.com
  smtp_port = 587
  smtp_user = user
  smtp_password = password
  }}}

  where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [https://gmail.com].

  Alternatively, you can use `smtp_port = 25`.[[br]]
  You should not use `smtp_port = 465`. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details.

  == Troubleshooting

  If notifications are not working, inspect the [TracLogging log] for error messages.

  Notification errors are not always reported through the web interface, so the user who submits a change or creates a ticket may not get notified about a notification failure. The Trac administrator needs to look at the log to find the error message and traceback.

  === ''Permission denied'' error

  Typical error message:
  {{{#!sh
    ...
    File ".../smtplib.py", line 303, in connect
      raise socket.error, msg
    error: (13, 'Permission denied')
  }}}

  This error usually comes from a security settings on the server: many Linux distributions do not allow the web server (Apache, ...) to post email messages to the local SMTP server.

  Many users get confused when their manual attempts to contact the SMTP server succeed:
  {{{#!sh
  telnet localhost 25
  }}}
  This is because a regular user may connect to the SMTP server, but the web server cannot:
  {{{#!sh
  sudo -u www-data telnet localhost 25
  }}}

  In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help in the Trac [trac:MailingList MailingList] archive.

  Relevant ML threads:
   * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518

  For SELinux in Fedora 10:
  {{{#!sh
  $ setsebool -P httpd_can_sendmail 1
  }}}

  === ''Suspected spam'' error

  Some SMTP servers may reject the notification email sent by Trac.

  The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' spam detection on sensitive email servers. In such an event, change the default encoding to "quoted-printable" using the `mime_encoding` option.

  Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.

  ----
  See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]


name: TracPermissions
author: trac
text:
  = Trac Permissions
  [[TracGuideToc]]

  Trac uses a simple, case sensitive, permission system to control what users can and can't access.

  Permissions are managed using the [TracAdmin trac-admin] tool or the ''General / Permissions'' panel in the ''Admin'' tab of the web interface.

  In addition to the default permission policy described in this page, it is possible to activate additional permission policies by enabling plugins and listing them in [TracIni#trac-permission_policies-option "[trac] permission_policies"]. See TracFineGrainedPermissions for more details.

  Non-authenticated users accessing the system are assigned the name //anonymous//. Assign permissions to the //anonymous// user to set privileges for anonymous/guest users. The parts of Trac that a user does not have privilege for will not be displayed in the navigation.
  In addition to these privileges, users can be granted additional individual rights in effect when authenticated and logged into the system. All logged in users belong to the virtual group //authenticated//, which inherits permissions from //anonymous//.

  == Graphical Admin Tab

  To access this tab, a user must have one of the following permissions: `TRAC_ADMIN`, `PERMISSION_ADMIN`, `PERMISSION_GRANT`, `PERMISSION_REVOKE`. The permissions can be granted using the `trac-admin` command with a more detailed description [#GrantingPrivileges below]:
  {{{#!sh
  $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
  }}}

  Then, the user `bob` will be able to see the Admin tab, and can access the permissions menu. This menu will allow you to perform all the following actions, but from the browser rather than requiring root access to the server. '''Use at least one lowercase character in user names, as all-uppercase names are reserved for permissions.'''

  [[Image(htdocs:../common/guide/admin.png)]]

  [[Image(htdocs:../common/guide/admin-permissions.png)]]

  [[Image(htdocs:../common/guide/admin-permissions-TICKET_ADMIN.png)]]

  From the graphical admin tab, users with `PERMISSION_GRANT` will only be allowed to grant permissions that they possess, and users with `PERMISSION_REVOKE` will only be allowed to revoke permissions that they possess. For example, a user cannot grant `MILESTONE_ADMIN` unless they have `PERMISSION_GRANT` and `MILESTONE_ADMIN`, and they cannot revoke `MILESTONE_ADMIN` unless they have `PERMISSION_REVOKE` and `MILESTONE_ADMIN`. `PERMISSION_ADMIN` just grants the user both `PERMISSION_GRANT` and `PERMISSION_REVOKE`, and users with `TRAC_ADMIN` can grant or revoke any permission.

  == Available Privileges

  To enable all privileges for a user, use the `TRAC_ADMIN` permission. This permission is like being `root` on a *NIX system: it will allow you to perform any operation.

  Otherwise, individual privileges can be assigned to users for the different functional areas of Trac and '''note that the privilege names are uppercase''':

  === Repository Browser

  || `BROWSER_VIEW` || View directory listings in the [TracBrowser repository browser] ||
  || `FILE_VIEW` || View files in the [TracBrowser repository browser] ||
  || `CHANGESET_VIEW` || View [TracChangeset repository check-ins] ||
  || `LOG_VIEW` || View revision logs of files and directories in the [TracBrowser repository browser] ||

  === Ticket System

  || `TICKET_VIEW` || View existing [TracTickets tickets] and perform [TracQuery ticket queries] ||
  || `TICKET_CREATE` || Create new [TracTickets tickets] ||
  || `TICKET_APPEND` || Add comments and attachments to [TracTickets tickets], and edit description of ticket the user created ||
  || `TICKET_CHGPROP` || Modify [TracTickets ticket] properties (priority, assignment, keywords, etc.) with the following exceptions: edit description of tickets created by others, add/remove other users from cc field when logged in ||
  || `TICKET_MODIFY` || Includes both `TICKET_APPEND` and `TICKET_CHGPROP`, and in addition allows resolving [TracTickets tickets] in the [TracWorkflow default workflow]. Tickets can be assigned to users through a [TracTickets#Assign-toasDrop-DownList drop-down list] when the list of possible owners has been restricted. ||
  || `TICKET_EDIT_CC` || Full modify cc field ||
  || `TICKET_EDIT_DESCRIPTION` || Modify description field. User with `TICKET_APPEND` or `TICKET_CHGPROP` can modify description of ticket they created. ||
  || `TICKET_EDIT_COMMENT` || Modify another user's comments. Any user can modify their own comments by default. ||
  || `TICKET_BATCH_MODIFY` || [TracBatchModify Batch modify] tickets ||
  || `TICKET_ADMIN` || All `TICKET_*` permissions, deletion of ticket attachments and modification of the reporter field, which grants ability to create a ticket on behalf of another user and it will appear that another user created the ticket. It also allows managing ticket properties through the web administration module. ||

  === Roadmap

  || `MILESTONE_VIEW` || View milestones and assign tickets to milestones. ||
  || `MILESTONE_CREATE` || Create new milestones ||
  || `MILESTONE_MODIFY` || Modify milestones ||
  || `MILESTONE_DELETE` || Delete milestones ||
  || `MILESTONE_ADMIN` || All `MILESTONE_*` permissions ||
  || `ROADMAP_VIEW` || View the [TracRoadmap roadmap] page, which is not yet the same as MILESTONE_VIEW, see [trac:#4292 #4292] ||
  || `ROADMAP_ADMIN` || to be removed with [trac:#3022 #3022], replaced by MILESTONE_ADMIN ||

  === Reports

  || `REPORT_VIEW` || View [TracReports reports], i.e. the //View Tickets// link. ||
  || `REPORT_SQL_VIEW` || View the SQL query of a [TracReports report] ||
  || `REPORT_CREATE` || Create new [TracReports reports] ||
  || `REPORT_MODIFY` || Modify [TracReports reports] ||
  || `REPORT_DELETE` || Delete [TracReports reports] ||
  || `REPORT_ADMIN` || All `REPORT_*` permissions ||

  === Wiki System

  || `WIKI_VIEW` || View [TracWiki wiki] pages ||
  || `WIKI_CREATE` || Create new [TracWiki wiki] pages ||
  || `WIKI_MODIFY` || Modify [TracWiki wiki] pages ||
  || `WIKI_RENAME` || Rename [TracWiki wiki] pages ||
  || `WIKI_DELETE` || Delete [TracWiki wiki] pages and attachments ||
  || `WIKI_ADMIN` || All `WIKI_*` permissions, plus the management of ''readonly'' pages. ||

  === Permissions

  || `PERMISSION_GRANT` || add/grant a permission ||
  || `PERMISSION_REVOKE` || remove/revoke a permission ||
  || `PERMISSION_ADMIN` || All `PERMISSION_*` permissions ||

  === Others

  || `TIMELINE_VIEW` || View the [TracTimeline timeline] page ||
  || `SEARCH_VIEW` || View and execute [TracSearch search] queries ||
  || `CONFIG_VIEW` || Enables additional sections on ''About Trac'' that show the current configuration and the list of installed plugins ||
  || `EMAIL_VIEW` || Shows email addresses even if [TracIni#trac-section trac show_email_addresses] configuration option is false ||

  == Attachment Permissions

  Attachment permissions are handled by `LegacyAttachmentPolicy`, and unlike the permissions discussed so far, the permissions provided by `LegacyAttachmentPolicy` are not directly granted. Rather, the ability to create, view and delete attachments is determined by the attachment's parent realm and permissions the user possesses for that realm.

  The attachment actions are determined by the following
  permissions in the ticket, wiki and milestone realms:
  {{{#!table class="listing"
  ||= Granted By: =||= Ticket =||= Wiki =||= Milestone =||
  || `ATTACHMENT_CREATE` || `TICKET_APPEND` || `WIKI_MODIFY` || `MILESTONE_MODIFY` ||
  || `ATTACHMENT_VIEW` || `TICKET_VIEW` || `WIKI_VIEW` || `MILESTONE_VIEW` ||
  || `ATTACHMENT_DELETE` || `TICKET_ADMIN` || `WIKI_DELETE` || `MILESTONE_DELETE` ||
  }}}

  An authenticated user can delete an attachment //they added// without possessing the permission
  that grants `ATTACHMENT_DELETE`.

  If explicit attachment permissions are preferred, `ATTACHMENT_CREATE`, `ATTACHMENT_DELETE` and `ATTACHMENT_VIEW` can be created using the [trac:ExtraPermissionsProvider]. The simplest implementation is to simply define the actions.
  {{{#!ini
  [extra-permissions]
  _perms = ATTACHMENT_CREATE, ATTACHMENT_DELETE, ATTACHMENT_VIEW
  }}}

  An alternative configuration adds an `ATTACHMENT_ADMIN` meta-permission that grants the other 3 permission.
  {{{#!ini
  [extra-permissions]
  ATTACHMENT_ADMIN = ATTACHMENT_CREATE, ATTACHMENT_DELETE, ATTACHMENT_VIEW
  }}}

  The explicit permissions can be used in concert with `LegacyAttachmentPolicy`, or `LegacyAttachmentPolicy` can be removed from `permission_policies`, in which case only users that have been explicitly granted the corresponding attachment actions will be able to create, delete and view attachments.

  == Granting Privileges

  You grant privileges to users using [TracAdmin trac-admin]. The current set of privileges can be listed with the following command:
  {{{#!sh
  $ trac-admin /path/to/projenv permission list
  }}}

  This command will allow the user ''bob'' to delete reports:
  {{{#!sh
  $ trac-admin /path/to/projenv permission add bob REPORT_DELETE
  }}}

  The `permission add` command also accepts multiple privilege names:
  {{{#!sh
  $ trac-admin /path/to/projenv permission add bob REPORT_DELETE WIKI_CREATE
  }}}

  Or add all privileges:
  {{{#!sh
  $ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
  }}}

  == Permission Groups

  There are two built-in groups, //authenticated// and //anonymous//.
  Any user who has not logged in is automatically in the //anonymous// group.
  Any user who has logged in is also in the //authenticated// group.
  The //authenticated// group inherits permissions from the //anonymous// group.
  For example, if the //anonymous// group has permission WIKI_MODIFY, it is not necessary to add the WIKI_MODIFY permission to the //authenticated// group as well.

  Custom groups may be defined that inherit permissions from the two built-in groups.

  Permissions can be grouped together to form roles such as ''developer'', ''admin'', etc.
  {{{#!sh
  $ trac-admin /path/to/projenv permission add developer WIKI_ADMIN
  $ trac-admin /path/to/projenv permission add developer REPORT_ADMIN
  $ trac-admin /path/to/projenv permission add developer TICKET_MODIFY
  $ trac-admin /path/to/projenv permission add bob developer
  $ trac-admin /path/to/projenv permission add john developer
  }}}

  Group membership can be checked by doing a {{{permission list}}} with no further arguments; the resulting output will include group memberships. '''Use at least one lowercase character in group names, as all-uppercase names are reserved for permissions'''.

  == Adding a New Group and Permissions
  Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group.

  The following will add ''bob'' to the new group called ''beta_testers'' and then will assign `WIKI_ADMIN` permissions to that group. Thus, ''bob'' will inherit the `WIKI_ADMIN` permission.
  {{{#!sh
  $ trac-admin /path/to/projenv permission add bob beta_testers
  $ trac-admin /path/to/projenv permission add beta_testers WIKI_ADMIN
  }}}

  == Removing Permissions

  Permissions can be removed using the 'remove' command.

  This command will prevent the user ''bob'' from deleting reports:
  {{{#!sh
  $ trac-admin /path/to/projenv permission remove bob REPORT_DELETE
  }}}

  Just like `permission add`, this command accepts multiple privilege names.

  You can also remove all privileges for a specific user:
  {{{#!sh
  $ trac-admin /path/to/projenv permission remove bob '*'
  }}}

  Or one privilege for all users:
  {{{#!sh
  $ trac-admin /path/to/projenv permission remove '*' REPORT_ADMIN
  }}}

  == Creating New Privileges

  To create custom permissions, for example to be used in a custom workflow, enable the optional [trac:ExtraPermissionsProvider tracopt.perm.config_perm_provider.ExtraPermissionsProvider] component in the "Plugins" admin panel, and add the desired permissions to the `[extra-permissions]` section in your [TracIni#extra-permissions-section trac.ini]. For more information, please refer to the documentation  on the [TracIni#extra-permissions-section TracIni] page after enabling the component.

  == Default Permissions

  By default on a new Trac installation, the //anonymous// user will have ''view'' access to everything in Trac, but will not be able to create or modify anything.
  On the other hand, the //authenticated// users will have the permissions to ''create and modify tickets and wiki pages''.

  //**anonymous**//
  {{{
  BROWSER_VIEW
  CHANGESET_VIEW
  FILE_VIEW
  LOG_VIEW
  MILESTONE_VIEW
  REPORT_SQL_VIEW
  REPORT_VIEW
  ROADMAP_VIEW
  SEARCH_VIEW
  TICKET_VIEW
  TIMELINE_VIEW
  WIKI_VIEW
  }}}

  //**authenticated**//
  {{{
  TICKET_CREATE
  TICKET_MODIFY
  WIKI_CREATE
  WIKI_MODIFY
  }}}
  ----
  See also: TracAdmin, TracFineGrainedPermissions


name: TracPlugins
author: trac
text:
  [[PageOutline(2-5,Contents,pullout)]]

  = Trac plugins

  Trac is extensible with [trac:PluginList plugins]. Plugin functionality is based on the [trac:TracDev/ComponentArchitecture component architecture], described in the [trac:TracDev/PluginDevelopment plugin development] page.

  == Plugin discovery

  From the user's point of view, a plugin is either a single .py file or a package (.egg or .whl). Trac looks for plugins in Python's `site-packages` directory, the [TracIni#GlobalConfiguration global shared] `plugins` directory and the [TracEnvironment project environment] `plugins` directory. Plugins installed to the project environment `plugins` directory are enabled, unless explicitly disabled in the `[components]` section of the `trac.ini` file.  Plugins installed elsewhere must be explicitly enabled in the [[TracIni#components-section| [components] ]] section of the `trac.ini` file.

  == Installing a Trac plugin

  The instructions below are applicable to a plugins installed as packages. Plugins implemented as a single `py` file should be downloaded and copied to the [TracEnvironment project environment] `plugins` directory or the [TracIni#GlobalConfiguration global shared] plugins directory.

  === For a single project

  Packages built for a single project must use the egg
  format, as the wheel format (described below) is not
  supported by the setuptools loading mechanism. Build the `egg` file from the plugin source:

  * Checkout or download and unpack the source.
  * Change to the directory containing `setup.py`.
  * Run:
   {{{#!sh
  $ python setup.py bdist_egg
  }}}
   The egg file will be created in the `dist` subdirectory.
  * Copy the egg file to the `plugins` directory of the [TracEnvironment project environment].

  Make sure the web server has sufficient permissions to read the plugin egg and restart the web server. If you are running as a [TracStandalone "tracd" standalone server], restart tracd (i.e. kill the process and run again).

  Trac also searches for plugins installed in the [TracIni#GlobalConfiguration global shared] plugins directory. This is a convenient way to share the installation of plugins across several, but not all, environments.

  '''Note''': The minor version number of the Python used to build the egg ''must'' match the minor version number of the Python running Trac. For example, if you are running Trac with Python 2.6, but build the egg with Python 2.7, the egg won't be recognized.

  '''Note''': In a multi-project setup, a pool of Python interpreters will be dynamically allocated to projects based on need. Since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all projects. In other words, you cannot use different versions of a plugin in different projects of a multi-project setup. Install plugins for all projects (see below) and enable them as needed for each project.

  ==== Uninstalling #UninstallEgg

  Remove the egg from the `plugins` directory and restart the web server.

  === For all projects

  ==== Using pip

  The modern Python package manager, `pip`, is included in Python 2.7.9 and later. In earlier versions of Python it can be installed through the package manager of your OS (e.g. `apt-get install python-pip`) or using [https://pip.pypa.io/en/latest/installing.html#install-pip get_pip.py].

  Using `pip`, the plugin will be installed
  in the [https://pythonwheels.com/ wheel format], which is the modern standard for Python and a
  replacement for the egg format.

  ==== From PyPI

  Some plugins, such as [th:TagsPlugin TracTags], can be installed directly from [https://pypi.org PyPI] using `pip`:
  {{{#!sh
  $ pip install TracTags
  }}}

  The version can be specified, which can be useful if you don't want to install the latest:
  {{{#!sh
  $ pip install TracTags==0.10
  }}}

  ==== From source

  You can install directly from a source repository:
  {{{#!sh
  $ pip install svn+https://trac-hacks.org/svn/tagsplugin/trunk
  }}}

  Replace the `svn+` prefix with `git+` if installing
  from a Git repository.

  Or from the path or URL of a tar.gz or zip archive:
  {{{#!sh
  $ pip install https://trac-hacks.org/browser/tagsplugin/trunk?format=zip
  }}}

  Or checkout the source and provide `pip` a path to the source directory:
  {{{#!sh
  $ svn co https://trac-hacks.org/svn/tagsplugin/trunk tractags
  $ pip install tractags
  }}}

  ==== Enabling the plugin

  Unlike plugins installed per environment, you have to explicitly enable globally installed plugins. This also applies to plugins installed in the shared plugins directory.

  This is done in the `[components]` section of the configuration file `trac.ini`. For example:
  {{{#!ini
  [components]
  tractags.* = enabled
  }}}

  The name of the option is the plugin package name. This should be specified in the documentation of the plugin, but can also be discovered by looking at the source: it is usually the top-level directory name containing a file named `__init__.py`.

  Plugins can also be enabled from the [#Web-basedpluginadministration administration] page.

  After installing the plugin, you must restart your web server.

  ==== Upgrading the environment

  Some plugins require an environment upgrade. This will typically be necessary for plugins that implement `IEnvironmentSetupParticipant`. Common reasons for requiring an environment upgrade are to add tables to the database or add configuration parameters to trac.ini. A notification will be displayed when accessing Trac for the first time after installing a plugin and restarting the web server. To upgrade the environment, run the command:

  {{{#!sh
  $ trac-admin /path/to/env upgrade
  }}}

  A database backup will be made before upgrading the environment, unless the `--no-backup` option is specified. For more information, refer to the documentation output by `trac-admin /path/to/env help upgrade`.

  ==== Redeploying static resources

  If you [TracInstall#MappingStaticResources mapped static resources] so they are served by the web server, and the plugin contains static resources (CSS, !JavaScript and image files), the resources will need to be deployed to the location on the filesystem that is served by the web server.

  Execute the `deploy` command, as is done during install and [TracUpgrade#a5.Refreshstaticresources upgrade]:

  {{{#!sh
  $ trac-admin /path/to/env deploy /deploy/path
  }}}

  After executing the command, you must restart your web server.

  {{{#!div style="border: 1pt dotted; margin: 1em"
  **Note:** Some web browsers (IE, Opera) cache CSS and Javascript files, so you should instruct your users to manually erase the contents of their browser's cache. A forced refreshed (SHIFT + <F5>) should be enough.
  {{{#!comment
  Remove above note once #9936 is fixed.
  }}}
  }}}

  ==== Uninstalling #UninstallWithPip

  Get a list of installed plugins:
  {{{#!sh
  $ pip list
  Package    Version
  ---------- -------
  Jinja2     2.10.1
  MarkupSafe 1.1.1
  pip        19.2.2
  setuptools 41.2.0
  Trac       1.4
  TracTags   0.10
  wheel      0.33.6
  }}}

  Uninstall a plugin by specifying the package name:
  {{{#!sh
  $ pip uninstall TracTags
  }}}

  == Web-based plugin administration

  The admin page offers limited support for plugin configuration to users with `TRAC_ADMIN` permission:

  * en/dis-abling installed plugins
  * installing plugins by uploading them as eggs

  If you wish to disable the second function for security reasons, add the following to your `trac.ini` file:
  {{{#!ini
  [components]
  trac.admin.web_ui.PluginAdminPanel = disabled
  }}}
  This disables the whole panel, so the first function will no longer be available.

  == Setting up the plugin cache

  Some plugins installed as eggs will need to be extracted by the Python egg's runtime (`pkg_resources`), so that their contents are actual files on the file system. The directory to which they are extracted defaults to `.python-eggs` in the home directory of the current user, which may or may not be a problem. You can, however, override the default location using the `PYTHON_EGG_CACHE` environment variable.

  To do this from the Apache configuration, use the `SetEnv` directive:
  {{{#!apache
  SetEnv PYTHON_EGG_CACHE /path/to/dir
  }}}

  This works whether you're using the [TracCgi CGI] or the [TracModPython mod_python] front-end. Put this directive next to where you set the path to the [TracEnvironment Trac environment], i.e. in the same `<Location>` block.

  For example for CGI:
  {{{#!apache
   <Location /trac>
     SetEnv TRAC_ENV /path/to/projenv
     SetEnv PYTHON_EGG_CACHE /path/to/dir
   </Location>
  }}}

  Or for mod_python:
  {{{#!apache
   <Location /trac>
     SetHandler mod_python
     ...
     SetEnv PYTHON_EGG_CACHE /path/to/dir
   </Location>
  }}}

  '''Note''': !SetEnv requires the `mod_env` module, which needs to be activated for Apache. In this case the !SetEnv directive can also be used in the `mod_python` Location block.

  For [TracFastCgi FastCGI], you'll need to `-initial-env` option, or whatever is provided by your web server for setting environment variables.

  '''Note''': if you already use -initial-env to set the project directory for either a single project or parent, you will need to add an additional -initial-env directive to the !FastCgiConfig directive:

  {{{#!apache
  FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
  }}}

  === About hook scripts

  If you have Subversion hook scripts that invoke Trac, such as the post-commit hook script provided in the `/contrib` directory, make sure you define the `PYTHON_EGG_CACHE` environment variable within these scripts.

  == Writing Trac Plugins

  You can write your own Trac plugin using the following resources:
  * [trac:TracDev Developer documentation]
  * [https://trac-hacks.org Examples on trac-hacks.org]
  * [trac:browser:branches/1.4-stable/sample-plugins sample-plugins]

  == Troubleshooting

  === Did you get the correct version of the Python egg?

  Python eggs have the Python version encoded in their filename. For example, `MyPlugin-1.0-py2.5.egg` is an egg for Python 2.5, and will '''not''' be loaded if you're running a different Python version (such as 2.4 or 2.6).

  Also, verify that the egg file you downloaded is indeed a .zip archive. If you downloaded it from a Trac site, you may have downloaded the HTML preview page instead.

  === Is the plugin enabled?

  If you install a plugin globally, i.e. ''not'' inside the `plugins` directory of the Trac project environment, you must explicitly enable it in [TracIni trac.ini]. Make sure that:

   * you added the necessary line(s) to the `[components]` section.
   * the package/module names are correct and do not contain typos.
   * the value is `enabled`, not `enable` or `Enable`.
   * the section name is `components`, not `component`.

  === Check the permissions

  Trac must be able to read the .py file or package (.egg or .whl).

  === Check the log files

  See [trac:TracTroubleshooting#ChecktheLogs].

  === Verify you have the proper permissions

  Some plugins require you have special permissions. !TracTags, for example, requires `TAGS_VIEW` permissions for the //Tags// navigation item to be added.

  === Is the wrong version of the plugin loading?

  If you put your plugins in one of the `plugins` directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:

  * Only one version of the plugin can be loaded for each running Trac server, i.e. each Python process. The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is `enabled` or `disabled` makes no difference.
  * A globally installed plugin will override any version in the global or project plugins directories. A plugin from the global plugins directory will be discovered ''before'' any project plugins directory.
  * If your Trac server hosts more than one project (as with `TRAC_ENV_PARENT_DIR` setups), having two versions of a plugin in two different projects will give unpredicatable results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first plugin found, usually from the project that receives the first request.
  * Having more than one version listed inside Python site-packages is fine, because setuptools will make sure you get the version installed most recently. However, don't store more than one version inside a global or project plugins directory: neither the version number nor the installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins.

  === If all of the above failed

  See TracSupport.

  ----
  See also TracGuide, TracIni.


name: TracQuery
author: trac
text:
  = Trac Ticket Queries
  [[TracGuideToc]]

  In addition to [TracReports reports], Trac provides ''custom ticket queries'', which display tickets meeting specified criteria.

  To configure and execute a custom query, navigate to the ''View Tickets'' module from the navigation bar, and select the ''New Custom Query'' link.

  == Filters

  When you first go to the query page, the default filter will display tickets relevant to you:
   * If logged in, all open tickets assigned to you.
   * If not logged in, but you have specified a name or email address in the preferences, all open tickets where your name or email is in the CC list.
   * If not logged in and no name/email is defined in the preferences, then all open issues.

  New filters are added using the dropdown lists at the bottom corners of the filters box; 'And' conditions on the left, 'Or' conditions on the right. Filters are removed by clicking the button to the left with the minus sign on the label.

  After you have edited your filters, click the ''Update'' button to refresh your results.

  Filters with either a text box or a dropdown menu of options can be added multiple times to perform an ''Or'' on the criteria. Add additional 'Or's by Clicking the 'And' Dropdown and selecting an item that you have already selected. For example, to select "Milestone is X ''Or'' Milestone is Y", Select 'Milestone', Select 'X', then click the 'And' Dropdown, select 'Milestone' a second time and select 'Y'.

  For text fields such as Keywords and CC the `-` operator can be used to negate a match and double quotes (//since 1.2.1//) can be used to match a phrase. For example, a //contains// match for `word1 word2 -word3 "word4 word5"` matches tickets containing `word1` and `word2`, not `word3` and `word4 word5`.

  You can use the controls just below the filters box to group the results based on a field, or display the full description for each ticket.

  Keyboard shortcuts are available for manipulating the //checkbox// filters:
  * Clicking on a filter row label toggles all checkboxes.
  * Pressing the modifier key while clicking on a filter row label inverts the state of all checkboxes.
  * Pressing the modifier key while clicking on a checkbox selects the checkbox and deselects all other checkboxes in the filter. Since 1.2.1 this also works for the //Columns// checkboxes.

  The modifier key is platform and browser dependent. On Mac the modified key is !Option/Alt or Command. On Linux the modifier key is Ctrl + Alt. Opera on Windows seems to use Ctrl + Alt, while Alt is effective for other Windows browsers.

  == Navigating Tickets

  Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Query'' link to return to the query page.

  You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Query'' links after saving your results. When you return to the query ''any tickets which were edited'' will be displayed with italicized text. If one of the tickets was edited such that [[html(<span style="color: grey">it no longer matches the query criteria </span>)]], the text will also be greyed. If '''a new ticket matching the query criteria has been created''', it will be shown in bold.

  The query results can be refreshed and cleared of these status indicators by clicking the ''Update'' button again.

  == Saving Queries

  Trac allows you to save the query as a named query accessible from the reports module. To save a query ensure that you have ''Updated'' the view and then click the ''Save query'' button displayed beneath the results.
  You can also save references to queries in Wiki content, as described below.

  '''Note:''' one way to easily build queries like the ones below is to create and test the queries using Custom Query module. Clicking ''Save query'' will display the query string for you, all you need to do is remove the extra line breaks.

  '''Note:''' you must have the '''REPORT_CREATE''' permission in order to save queries to the list of default reports. The ''Save query'' button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query.

  == TracLinks to Queries

  You can make a link to a query from any Wiki page using a simple [TracQuery#QueryLanguage query language] to specify the criteria.
  {{{
  [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
  }}}

  Which is displayed as:
    [query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]

  Alternatively, you can copy the query string from the browser URL box and paste it into the Wiki link, including the leading `?` character:
  {{{
  [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
  }}}

  Which is displayed as:
    [query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]

  == Query Language

  The `query:` TracLinks and the [TicketQuery "[[TicketQuery]]"] macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (`&`). Each filter consists of the ticket field name, an operator and one or more values. Multiple values are separated using a pipe (`|`), meaning the filter matches any of the values. To include a literal `&` or `|` in a value, escape the character with a backslash (`\`).

  The available operators are:
  || '''`=`''' || the field content exactly matches one of the values ||
  || '''`~=`''' || the field content contains one or more of the values ||
  || '''`^=`''' || the field content starts with one of the values ||
  || '''`$=`''' || the field content ends with one of the values ||

  All of these operators can also be negated:
  || '''`!=`''' || the field content matches none of the values ||
  || '''`!~=`''' || the field content does not contain any of the values ||
  || '''`!^=`''' || the field content does not start with any of the values ||
  || '''`!$=`''' || the field content does not end with any of the values ||

  Filters combining matches and negated matches can be constructed for text fields such as Keywords and CC using the //contains// (`~=`) operator. The `-` operator is used to negate a match and double quotes (//since 1.2.1//) are used for whitespace-separated words in a phrase. For example, `keywords~=word1 word2 -word3 "word4 word5"` matches tickets containing `word1` and `word2`, not `word3` and also `word4 word5`.
  || '''`status=closed,keywords~=firefox`''' || query closed tickets that contain keyword `firefox` ||
  || '''`status=closed,keywords~=opera`''' || query closed tickets that contain keyword `opera` ||
  || '''`status=closed,keywords~=firefox opera`''' || query closed tickets that contain keywords `firefox` and `opera` ||
  || '''`status=closed,keywords~=firefox|opera`''' || query closed tickets that contain keywords `firefox` or `opera` ||
  || '''`status=closed,keywords~=firefox,or,keywords~=opera`''' || query closed tickets that contain keyword `firefox`, or (closed or unclosed) tickets that contain keyword `opera` ||
  || '''`status=closed,keywords~=firefox -opera`''' || query closed tickets that contain keyword `firefox`, but not `opera` ||
  || '''`status=closed,keywords~=opera -firefox`''' || query closed tickets that contain keyword `opera`, but no `firefox` ||

  The date fields `created` and `modified` and custom fields of type `time` can be constrained by using the `=` operator and specifying a value containing two dates separated by two dots (`..`). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be omitted to avoid having to quote the query string.
  || '''`created=2007-01-01..2008-01-01`''' || query tickets created in 2007 ||
  || '''`created=lastmonth..thismonth`''' || query tickets created during the previous month ||
  || '''`modified=1weekago..`''' || query tickets that have been modified in the last week ||
  || '''`modified=..30daysago`''' || query tickets that have been inactive for the last 30 days ||

  Note that `modified` is the //last modified time//, so `modified` with a date range shows ticket that were //last modified// in that date range. If a ticket was modified in the date range, but modified again after the end date, it will not be included in the results.

  ----
  See also: TracTickets, TracReports, TicketQuery


name: TracReports
author: trac
text:
  = Trac Reports

  [[TracGuideToc]]

  The Trac reports module provides a simple, yet powerful reporting facility to present information about tickets in the Trac database.

  Rather than have its own report definition format, TracReports relies on standard SQL `SELECT` statements for custom report definition.

    '''Note:''' The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.

    You can already completely replace the reports module by the query module simply by disabling the former in [wiki:TracIni trac.ini]:
    {{{#!ini
    [components]
    trac.ticket.report.* = disabled
    }}}
    This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.

  A report consists of these basic parts:
   * '''ID''' — Unique (sequential) identifier
   * '''Title''' — Descriptive title
   * '''Description''' — A brief description of the report, in WikiFormatting text.
   * '''Report Body''' — List of results from report query, formatted according to the methods described below.
   * '''Footer''' — Links to alternative download formats for this report.

  == Changing Sort Order

  Simple reports - ungrouped reports to be specific - can be sorted by clicking the column header.

  If a column header is a hyperlink (red), click the column to sort by it. Clicking the same header again reverses the sort order.

  == Navigating Tickets

  Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' contextual navigation links, or click the ''Back to Report'' link to return to the report page.

  You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, in contrast to the query results (see TracQuery#NavigatingTickets).

  == Alternate Download Formats

  In addition to the HTML view, reports can also be exported in a number of alternate formats.
  At the bottom of the report page, you will find a list of available data formats. Click the desired link to
  download the alternate format.

  === Comma-delimited - CSV (Comma Separated Values)

  Export the report as plain text, each row on its own line, columns separated by a single comma (',').
  '''Note:''' The output is fully escaped so carriage returns, line feeds, and commas will be preserved in the output.

  === Tab-delimited

  Like above, but uses tabs (\t) instead of comma.

  === RSS - XML Content Syndication

  All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac.

  == Creating Custom Reports

  Creating a custom report requires a comfortable knowledge of SQL.

  Note that you need grant [TracPermissions#Reports permissions] in order to see the buttons for adding or editing reports.

  A report is basically a single named SQL query, executed and presented by Trac. Reports can be viewed and created from a custom SQL expression directly in the web interface.

  Typically, a report consists of a SELECT-expression from the 'ticket' table, using the available columns and sorting the way you want it.

  == Ticket columns

  The ''ticket'' table has the following columns:
   * id
   * type
   * time
   * changetime
   * component
   * severity
   * priority
   * owner
   * reporter
   * cc
   * version
   * milestone
   * status
   * resolution
   * summary
   * description
   * keywords

  See TracTickets for a detailed description of the column fields.

  Example: '''All active tickets, sorted by priority and time'''
  {{{#!sql
  SELECT id AS ticket, status, severity, priority, owner, time AS created, summary
  FROM ticket
  WHERE status IN ('new', 'assigned', 'reopened')
  ORDER BY priority, time
  }}}

  == Advanced Reports: Dynamic Variables

  For more flexible reports, Trac supports the use of ''dynamic variables'' in report SQL statements.
  In short, dynamic variables are ''special'' strings that are replaced by custom data before query execution. Dynamic variables are entered through the preferences form and the values are autocompleted //(Since 1.3.2)//.

  === Using Variables in a Query

  The syntax for dynamic variables is simple, any upper case word beginning with `$` is considered a variable.

  Example:
  {{{#!sql
  SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
  }}}

  The value of the dynamic variable can be assigned in the report preferences form.

  To assign a value to `$PRIORITY` in the URL for a report, leave out the leading `$`:
  {{{
   https://trac.edgewall.org/reports/14?PRIORITY=high
  }}}

  To use multiple variables, separate them with an `&`:
  {{{
   https://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical
  }}}

  It is possible to assign a default value to the variable, within a SQL comment:

  {{{#!sql
  -- PRIORITY = high

  SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
  }}}


  === !Special/Constant Variables

  There is one dynamic variable whose value is set automatically (the URL does not have to be changed) to allow practical reports.

   * $USER — Username of logged in user.

  Example: List all tickets assigned to me:
  {{{#!sql
  SELECT id AS ticket,summary FROM ticket WHERE owner=$USER
  }}}

  == Advanced Reports: Custom Formatting

  Trac is also capable of more advanced reports, including custom layouts, result grouping and user-defined CSS styles. To create such reports, we will use specialized SQL statements to control the output of the Trac report engine.

  === Special Columns

  To format reports, TracReports look for 'magic' column names in the query result. These 'magic' names are processed and affect the layout and style of the final report.

  === Automatically formatted columns

   * '''ticket''' — Ticket ID number. Becomes a hyperlink to that ticket.
   * '''id''' — same as '''ticket''' above when '''realm''' is not set
   * '''realm''' — together with '''id''', can be used to create links to other resources than tickets (e.g. a realm of ''wiki'' and an ''id'' to a page name will create a link to that wiki page)
     - for some resources, it may be necessary to specify their ''parent'' resources (e.g. for ''changeset'', the ''repos'') and this can be achieved using the '''parent_realm''' and '''parent_id''' columns
   * '''created, modified, date, time''' — Format cell as a date and/or time.
   * '''description''' — Ticket description field, parsed through the wiki engine.

  '''Example:'''
  {{{#!sql
  SELECT id AS ticket, created, status, summary FROM ticket
  }}}

  Those columns can also be defined but marked as hidden, see [#column-syntax below].

  See [trac:CookBook/Configuration/Reports] for examples of creating reports for realms other than ''ticket''.

  === Custom formatting columns

  Columns whose names begin and end with 2 underscores (e.g. '''`__color__`''') are
  assumed to be ''formatting hints'', affecting the appearance of the row.

   * '''`__group__`''' — Group results based on values in this column. Each group will have its own header and table.
   * '''`__grouplink__`''' — Make the header of each group a link to the specified URL. The URL is taken from the first row of each group.
   * '''`__color__`''' — Should be a numeric value ranging from 1 to 5 to select a pre-defined row color. Typically used to color rows by issue priority.
   {{{#!html
  <div style="margin-left:3em">Defaults:
  <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span>
  <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span>
  <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fbfbfb; border-color: #ddd; color: #444">Color 3</span>
  <span style="border: none; color: #333; background: transparent; font-size: 85%; background: #e7ffff; border-color: #cee; color: #099">Color 4</span>
  <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #e7eeff; border-color: #cde; color: #469">Color 5</span>
  </div>
  }}}
   * '''`__style__`''' — A custom CSS style expression to use on the `<tr>` element of the current row.
   * '''`__class__`''' — Zero or more space-separated CSS class names to be set on the `<tr>` element of the current row. These classes are added to the class name derived from `__color__` and the odd / even indicator.

  '''Example:''' List active tickets, grouped by milestone, group header linked to milestone page, colored by priority:
  {{{#!sql
  SELECT p.value AS __color__,
       t.milestone AS __group__,
       '../milestone/' || t.milestone AS __grouplink__,
       (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
       t.id AS ticket, summary
  FROM ticket t,enum p
  WHERE t.status IN ('new', 'assigned', 'reopened')
    AND p.name = t.priority AND p.type = 'priority'
  ORDER BY t.milestone, p.value, t.severity, t.time
  }}}

  Note that table join is used to match ''ticket'' priorities with their numeric representation from the ''enum'' table.

  === Changing layout of report rows === #column-syntax

  By default, all columns on each row are display on a single row in the HTML report, possibly formatted according to the descriptions above. However, it is also possible to create multi-line report entries.

   * '''`column_`''' — ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be continued on a second line.

   * '''`_column_`''' — ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.

   * '''`_column`''' — ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).
     This can be used to hide any kind of column, even important ones required for identifying the resource, e.g. `id as _id` will hide the '''Id''' column but the link to the ticket will be present.

  '''Example:''' List active tickets, grouped by milestone, colored by priority, with  description and multi-line layout:

  {{{#!sql
  SELECT p.value AS __color__,
         t.milestone AS __group__,
         (CASE owner
            WHEN 'daniel' THEN 'font-weight: bold; background: red;'
            ELSE '' END) AS __style__,
         t.id AS ticket, summary AS summary_,             -- ## Break line here
         component,version, severity, milestone, status, owner,
         time AS created, changetime AS modified,         -- ## Dates are formatted
         description AS _description_,                    -- ## Uses a full row
         changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
  FROM ticket t,enum p
  WHERE t.status IN ('new', 'assigned', 'reopened')
    AND p.name = t.priority AND p.type = 'priority'
  ORDER BY t.milestone, p.value, t.severity, t.time
  }}}

  === Reporting on custom fields

  If you have added [TracTicketsCustomFields custom fields] to your tickets, you can write a SQL query to include them in a report. You'll need to make a join on the `ticket_custom` table.

  If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the `ticket_custom` table. To get around this, use SQL's `LEFT OUTER JOIN` clauses. See [trac:TracIniReportCustomFieldSample TracIniReportCustomFieldSample] for some examples.

  === A note about SQL rewriting #rewriting

  Beyond the relatively trivial replacement of dynamic variables, the SQL query is also altered in order to support two features of the reports:
   1. [#sort-order sorting]
   1. pagination: limiting the number of results displayed on each page
  In order to support the first feature, the sort column is inserted in the `ORDER BY` clause in the first position or in the second position if a `__group__` column is specified (an `ORDER BY` clause is created if needed). In order to support pagination, a `LIMIT ... OFFSET ...` clause is appended.
  The query might be too complex for the automatic rewrite to work correctly, resulting in an erroneous query. In this case you still have the possibility to control exactly how the rewrite is done by manually inserting the following tokens:
   - `@SORT_COLUMN@`, the place where the name of the selected sort column will be inserted,
   - `@LIMIT_OFFSET@`, the place where the pagination support clause will be added
  Note that if you write them after an SQL comment, `--`, you'll effectively disable rewriting if this is what you want!

  Let's take an example, consider the following SQL query:
  {{{#!sql
  -- ## 4: Assigned, Active Tickets by Owner ## --

  --
  -- List assigned tickets, group by ticket owner, sorted by priority.
  --

  SELECT p.value AS __color__,
     owner AS __group__,
     id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
  FROM ticket t,enum p
  WHERE status = 'assigned'
    AND p.name = t.priority AND p.type = 'priority'
  ORDER BY __group__, p.value, severity, time
  }}}

  The automatic rewrite will be the following (4 rows per page, page 2, sorted by `component`):
  {{{#!sql
  SELECT p.value AS __color__,
     owner AS __group__,
     id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
  FROM ticket t,enum p
  WHERE status = 'assigned'
    AND p.name = t.priority AND p.type = 'priority'
  ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time
  LIMIT 4 OFFSET 4
  }}}

  The equivalent SQL query with the rewrite tokens would have been:
  {{{#!sql
  SELECT p.value AS __color__,
     owner AS __group__,
     id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter
  FROM ticket t,enum p
  WHERE status = 'assigned'
    AND p.name = t.priority AND p.type = 'priority'
  ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time
  @LIMIT_OFFSET@
  }}}

  If you want to always sort first by priority and only then by the user selected sort column, simply use the following `ORDER BY` clause:
  {{{#!sql
  ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time
  }}}

  == Changing Report Numbering

  There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema:
   * id integer PRIMARY KEY
   * author text
   * title text
   * query text
   * description text
  Changing the ID changes the shown order and number in the ''Available Reports'' list and the report's perma-link. This is done by running something like:
  {{{#!sql
  UPDATE report SET id = 5 WHERE id = 3;
  }}}
  Keep in mind that the integrity has to be maintained, i.e. ID has to be unique, and you don't want to exceed the max for your database.

  You may also need to update or remove the report number stored in the report or query.

  ----
  See also: TracTickets, TracQuery, [https://www.sqlite.org/lang_expr.html Query Language Understood by SQLite]


name: TracRepositoryAdmin
author: trac
text:
  = Repository Administration
  [[PageOutline(2-3)]]

  == Quick start #QuickStart

   * Enable the repository connector(s) for the version control system(s) that you will use.
   * Add repositories through the //Repositories// admin page, using `trac-admin` or by editing the `[repositories]` section of [[wiki:TracIni#repositories-section|trac.ini]].
   * Synchronize the repositories with the cache, if using cached repositories.
   * Configure your repository hooks to synchronize the repository. Alternatively you can synchronize on every request or disable the use of cached repositories, both of which have performance drawbacks and reduced functionality, but are easier to configure.

  == Enabling the components

  Support for version control systems is provided by optional components distributed with Trac, which are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them.

  The version control systems can be enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components through the //Plugins// admin page.

  {{{#!ini
  tracopt.versioncontrol.svn.* = enabled
  }}}

  {{{#!ini
  tracopt.versioncontrol.git.* = enabled
  }}}

  == Specifying repositories #Repositories

  Trac supports multiple repositories per environment, and the repositories may be for different version control systems. Each repository must be defined in a repository configuration provider. Repository providers included with Trac are the [#ReposDatabase database store], the [#ReposTracIni trac.ini configuration file] and the [#ReposGitWeb GitWeb configuration file]. Additional providers are available as plugins.

  You can define your repositories through a mix of providers, but each repository should only be defined in a single provider. The repository names must be unique across all providers and duplicate names are discarded.

  It is possible to define aliases of repositories that act as "pointers" to real repositories. This can be useful when renaming a repository, to avoid breaking links to the old name.

  === Default Repository

  Trac's repositories are listed in the Repository Index when navigating to //Browse Source//. The default repository is displayed first, followed by the Repository Index. TracLinks without a repository name in the path specification (e.g. `[1]` rather than `[1/repos1]`) refer to the default repository. !TracLinks for repositories other than the default must include the repository name in the path specification.

  From the Repository Admin page, the default repository is specified by leaving the //Name// attribute empty. From the command line, the default repository is specified using the string `(default)` or `""`. In TracIni, the default repository is specified by leaving the `{name}` empty for each `{name}.{attribute}` option (e.g. `.dir = /path/to/dir`).

  === Repository Attributes

  There are a number of attributes that can be specified for each repository, and additional attributes may be available through plugins. A repository `name` and one of the `alias` or `dir` attributes are mandatory. All others are optional.

  The following attributes are supported:

  ||='''Attribute''' =||='''Description''' =||
  ||`alias` ||\
  ||Defines an alias to a real repository. All TracLinks referencing the alias resolve to the aliased repository. Note that multiple indirection is not supported, so an alias must always point to a real repository. The `alias` and `dir` attributes are mutually exclusive. ||
  || `cached` ||\
  || For a version control system that support caching, specifies that repository caching should be used. Defaults to `true` for version control systems that support caching. ||
  ||`description` ||\
  ||The text specified in the `description` attribute is displayed below the top-level entry for the repository in the source browser. It supports WikiFormatting. ||
  ||`dir` ||\
  ||The `dir` attribute specifies the location of the repository in the filesystem. The `alias` and `dir` attributes are mutually exclusive. ||
  ||`hidden` ||\
  || When set to `true`, the repository is hidden from the repository index page in the source browser. Browsing the repository is still possible, and links referencing the repository remain valid. ||
  ||`sync_per_request`||\
  || When set to `true` the repository will be synchronized on every request (implicit synchronization). This is generally not recommended. See [#Synchronization repository synchronization] for a comparison of explicit and implicit synchronization. The attribute defaults to `false`. ||
  ||`type` ||\
  || The `type` attribute specifies the version control system used by the repository. Trac provides support for Subversion and Git, and plugins add support for several other systems. If `type` is not specified, it defaults to the value of the `[versioncontrol]` [wiki:TracIni#versioncontrol-default_repository_type-option default_repository_type] option. ||
  ||`url` ||\
  || The `url` attribute specifies the root URL to be used for checking out from the repository. When specified, a "Repository URL" link is added to the context navigation links in the source browser, that can be copied into the tool used for creating the working copy. ||

  === Scoped Repository

  For some version control systems, it is possible to specify not only the path to the repository in the `dir` attribute, but also a ''scope'' within the repository. Trac will then only show information related to the files and changesets below that scope. The scope is specified by appending a path that is relative to the repository root. The Subversion backend for Trac supports this.

  For example, assume a repository at filesystem path `/var/svn/repos1` with several directories at the root of the repository: `/proj1`, `/proj2`, etc. The following configuration would scope the repository to `/proj1`:
  {{{#!ini
  proj1.dir = /var/svn/repos1/proj1
  proj1.type = svn
  }}}

  For other repository types, check the corresponding plugin's documentation.

  === In the database #ReposDatabase
  Repositories can also be specified in the database, using either the //Repositories// admin page under //Version Control//, or the `trac-admin $ENV repository` commands.

  The admin panel shows the list of all repositories defined in the Trac environment. It allows adding repositories and aliases, editing repository attributes and removing repositories. Note that repositories defined in `trac.ini` are displayed but cannot be edited.

  The following [wiki:TracAdmin trac-admin] commands can be used to perform repository operations from the command line.

   `repository add <repos> <dir> [type]`::
     Add a repository `<repos>` located at `<dir>`, and optionally specify its type.

   `repository alias <name> <target>`::
     Create an alias `<name>` for the repository `<target>`.

   `repository remove <repos>`::
     Remove the repository `<repos>`.

   `repository set <repos> <key> <value>`::
     Set the attribute `<key>` to `<value>` for the repository `<repos>`.

  Note that the default repository has an empty name, so it will need to be quoted when running `trac-admin` from a shell. Alternatively, the name `(default)` can be used instead, for example when running `trac-admin` in interactive mode.

  === In `trac.ini` #ReposTracIni
  Repositories and repository attributes can be specified in the `[repositories]` section of [wiki:TracIni#repositories-section trac.ini]. Every attribute consists of a key structured as `{name}.{attribute}` and the corresponding value separated with an equal sign (`=`). The name of the default repository is empty.

  The main advantage of specifying repositories in `trac.ini` is that they can be inherited from a [wiki:TracIni#GlobalConfiguration global configuration]. Cached repositories defined in `trac.ini` at the time of [TracEnvironment#SourceCodeRepository environment initialization] will be automatically synchronized if the repository's connector is enabled. One drawback is that due to limitations in the `ConfigParser` class used to parse `trac.ini`, the repository name is always lowercase.

  The following example defines two Subversion repositories named `project` and `lib`, and an alias to `project` as the default repository. This is a typical use case where a Trac environment previously had a single repository (the `project` repository), and was converted to multiple repositories. The alias ensures that links predating the change continue to resolve to the `project` repository.
  {{{#!ini
  [repositories]
  project.dir = /var/repos/project
  project.description = This is the ''main'' project repository.
  project.type = svn
  project.url = http://example.com/svn/project
  project.hidden = true

  lib.dir = /var/repos/lib
  lib.description = This is the secondary library code.
  lib.type = svn
  lib.url = http://example.com/svn/lib

  .alias = project
  }}}
  Note that `name.alias = target` makes `name` an alias for the `target` repo, not the other way around.

  === In !GitWeb #ReposGitWeb

  [https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb GitWeb] is a CGI script that comes with Git for web-based visualization of repositories. Trac can read the gitweb-formatted `project.lists` file. The configuration is done through the `[gitweb-repositories]` section of [[TracIni#gitweb-repositories-section|trac.ini]].

  == Repository caching

  Caching improves the performance browsing the repository, viewing logs and viewing changesets. Cached repositories must be [#Synchronization synchronized], using either explicit or implicit synchronization. When searching changesets, only cached repositories are searched.

  Repositories that support caching are cached by default. The Subversion and Git backends support caching. The [trac:TracMercurial Mercurial plugin] does not yet support caching ([trac:#8417]). To disable caching, set the `cached` attribute to `false`.

  After adding a cached repository, the cache must be populated with the `trac-admin $ENV repository resync` command.

   `repository resync <repos>`::
     Re-synchronize Trac with a repository.

  == Repository synchronization #Synchronization

  Either explicit or implicit synchronization can be used. Implicit synchronization is easier to configure, but may result in noticeably worse performance. The changeset added and modified events can't be triggered with implicit synchronization, so the [#Automaticchangesetreferencesintickets commit ticket updater] won't be available.

  === Explicit synchronization #ExplicitSync

  This is the preferred method of repository synchronization. It requires adding a call to `trac-admin` in the `post-commit` hook of each repository. Additionally, if a repository allows changing revision metadata, a call to `trac-admin` must be added to the `post-revprop-change` hook as well.

   `changeset added <repos> <rev> [...]`::
     Notify Trac that one or more changesets have been added to a repository.

   `changeset modified <repos> <rev> [...]`::
     Notify Trac that metadata on one or more changesets in a repository has been modified.

  The `<repos>` argument can be either a repository name (use `"(default)"` for the default repository) or the path to the repository.

  Note that you may have to set the environment variable `PYTHON_EGG_CACHE` to the same value as was used for the web server configuration before calling `trac-admin`, if you changed it from its default location. See [wiki:TracPlugins#Settinguptheplugincache TracPlugins] for more information.

  ==== Subversion

  ===== Using `trac-svn-hook`

  In a Unix environment, the simplest way to configure explicit synchronization is by using the [trac:source:branches/1.4-stable/contrib/trac-svn-hook contrib/trac-svn-hook] script. `trac-svn-hook` starts `trac-admin` asynchronously to avoid slowing the commit and log editing operations. The script comes with a number of safety checks and usage advice. Output is written to a log file with prefix `svn-hooks-` in the environment `log` directory, which can make configuration issues easier to debug.

  There's no equivalent `trac-svn-hook.bat` for Windows yet, but the script can be run by Cygwin's bash. The documentation header of `trac-svn-hook` contains a Cygwin configuration example.

  Follow the help in the documentation header of the script to configure `trac-svn-hook`. You'll need to minimally set the `TRAC_ENV` variable, and may also need to set `TRAC_PATH` and `TRAC_LD_LIBRARY_PATH` for a non-standard installation or a virtual environment.

  Configuring the hook environment variables is even easier in Subversion 1.8 and later using the [http://svnbook.red-bean.com/en/1.8/svn.reposadmin.create.html#svn.reposadmin.hooks.configuration hook script environment] configuration. Rather than directly editing `trac-svn-hook` to set the environment variables, or exporting them from the hook that invokes `trac-svn-hook`, they can be configured through the repository `conf/hooks-env` file.

  Here is an example, using a Python virtual environment at `/usr/local/venv`:
  {{{#!ini
  [default]
  TRAC_ENV=/var/trac/project-1
  TRAC_PATH=/usr/local/venv/bin
  }}}

  ===== Writing Your Own Hook Script

  The following examples are complete post-commit and post-revprop-change scripts for Subversion. They should be edited for the specific environment, marked executable (where applicable) and placed in the `hooks` directory of each repository. On Unix (`post-commit`):
  {{{#!sh
  #!/bin/sh
  export PYTHON_EGG_CACHE="/path/to/dir"
  /usr/bin/trac-admin /path/to/env changeset added "$1" "$2"
  }}}
  Adapt the path to the actual location of `trac-admin`.
  On Windows (`post-commit.cmd`):
  {{{#!bat
  @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset added "%1" "%2"
  }}}

  The post-revprop-change hook for Subversion is very similar. On Unix (`post-revprop-change`):
  {{{#!sh
  #!/bin/sh
  export PYTHON_EGG_CACHE="/path/to/dir"
  /usr/bin/trac-admin /path/to/env changeset modified "$1" "$2"
  }}}
  On Windows (`post-revprop-change.cmd`):
  {{{#!bat
  @C:\Python26\Scripts\trac-admin.exe C:\path\to\env changeset modified "%1" "%2"
  }}}

  The Unix variants above assume that the user running the Subversion commit has write access to the Trac environment, which is the case in the standard configuration where both the repository and Trac are served by the web server. If you access the repository through another means, for example `svn+ssh://`, you may have to run `trac-admin` with different privileges, for example by using `sudo`.

  See the [http://svnbook.red-bean.com/en/1.7/svn.reposadmin.create.html#svn.reposadmin.create.hooks section about hooks] in the Subversion book for more information. Other repository types will require different hook configuration.

  ==== Git

  [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks Git hooks] can be used in the same way for explicit syncing of Git repositories.

  If your repository is one that only gets pushed to, add the following to the `hooks/post-receive` file in the repo:
  {{{#!sh
  #!/bin/sh
  tracenv=/path/to/env  # set to your Trac environment's path
  repos=                # set to your repository's name
  while read oldrev newrev refname; do
      if [ "$oldrev" = 0000000000000000000000000000000000000000 ]; then
          git rev-list --reverse "$newrev" --
      else
          git rev-list --reverse "$newrev" "^$oldrev" --
      fi | xargs trac-admin "$tracenv" changeset added "$repos"
  done
  }}}
  The `repos` variable is the repository name (use `"(default)"` for the default repository).

  Alternatively, if your git repository is one that gets committed to directly on the machine that hosts Trac, add the following to the `hooks/post-commit` file in your Git repository:
  {{{#!sh
  #!/bin/sh
  tracenv=/path/to/env  # set to your Trac environment's path
  repos=                # set to your repository's name
  REV=$(git rev-parse HEAD)
  trac-admin "$tracenv" changeset added "$repos" $REV
  }}}
  The `post-commit` hook will do nothing if you only update the repository by pushing to it.

  Be sure to set the hook scripts as executable.

  ==== Mercurial

  For Mercurial, add the following entries to the `.hgrc` file of each repository accessed by Trac (if [trac:TracMercurial] is installed in a Trac `plugins` directory, download [trac:source:mercurial-plugin/tracext/hg/hooks.py hooks.py] and place it somewhere accessible):
  {{{#!ini
  [hooks]
  ; If mercurial-plugin is installed globally
  commit = python:tracext.hg.hooks.add_changesets
  changegroup = python:tracext.hg.hooks.add_changesets

  ; If mercurial-plugin is installed in a Trac plugins directory
  commit = python:/path/to/hooks.py:add_changesets
  changegroup = python:/path/to/hooks.py:add_changesets

  [trac]
  env = /path/to/env
  trac-admin = /path/to/trac-admin
  }}}

  === Per-request synchronization #PerRequestSync
  If the post-commit hooks are not available, the environment can be set up for per-request synchronization. The `sync_per_request` attribute for each repository in the database and in [wiki:TracIni#trac-section trac.ini] must be set to `true`.

  Note that in this case, the changeset listener extension point is not called, and therefore plugins that depend on the changeset added and modified events won't work correctly. For example, automatic changeset references cannot be used with implicit synchronization.

  == Automatic changeset references in tickets #CommitTicketUpdater

  You can automatically add a reference to the changeset as a ticket comment whenever changes are committed to the repository. The description of the commit needs to contain one of the following patterns:
   * '''`Refs #123`''' - to reference this changeset in `#123` ticket
   * '''`Fixes #123`''' - to reference this changeset and close `#123` ticket with the default status ''fixed''

  This functionality requires installing a post-commit hook as described in [#ExplicitSync explicit synchronization], and enabling the optional commit updater components through the //Plugins// admin panel or by adding the following line to the `[components]` section of your [wiki:TracIni#components-section trac.ini]:
  {{{#!ini
  tracopt.ticket.commit_updater.* = enabled
  }}}
  For more information, see the documentation of the `CommitTicketUpdater` component in the //Plugins// admin panel and the [trac:CommitTicketUpdater] page.

  == Troubleshooting

  === My trac-post-commit-hook doesn't work anymore #trac-post-commit-hook

  You must now use the optional components from `tracopt.ticket.commit_updater.*`, which you can activate through the //Plugins// admin page, or by directly modifying the [TracIni#components-section "[components]"] section in the trac.ini. Be sure to use [#ExplicitSync explicit synchronization].

  See [trac:CommitTicketUpdater#Troubleshooting] for more troubleshooting tips.

  === Git control files missing

  If your repository is not browseable and you find a message in the log that looks like:
  {{{
  2017-08-08 10:49:17,339 Trac[PyGIT] ERROR: GIT control files missing in '/path/to/git-repository'
  2017-08-08 10:49:17,339 Trac[git_fs] ERROR: GitError: GIT control files not found, maybe wrong directory?
  }}}

  First check that the path to your repository is correct. If the path is correct, you may have a permission problem whereby the web server cannot access the repository. You can use Git to verify the repository. On a Debian-like Linux OS, the following command should help:
  {{{#!sh
  $ sudo -u www-data git --git-dir=/path/to/git-repository fsck
  }}}

  On other platforms you may need to modify the command to use the user under which the webserver runs.


name: TracRevisionLog
author: trac
text:
  = Viewing Revision Logs
  [[TracGuideToc]]

  Each path in the //Repository Browser// contains a contextual navigation link to the //Revision Log//. The //Revision Log// displays a list of the most recent changesets in which the current path or any other path below it has been modified.

  == The Revision Log Form

  It is possible to set the revision at which the revision log should start, using the ''View log starting at'' field. An empty value or a value of ''head'' is interpreted as the newest changeset.

  It is also possible to specify the revision at which the log should stop, using the ''Back to'' field. By default it is empty,
  which means the revision log will show the [TracIni#revisionlog-default_log_limit-option default log limit], which defaults to the latest 100 revisions.

  There are three modes of operation of the revision log.

  By default, the revision log ''stops on copy'', which means that whenever an ''Add'', ''Copy'' or ''Rename'' operation is detected, no older revision will be shown. That's very convenient when working with branches, as one only sees the history for that branch.

  It is also possible to indicate that one wants include what happened before a ''Copy'' or ''Rename'' change, by selecting the
  ''Follow copies'' mode. This will continue to list all revisions across copies and renames.
  Each time the name of the path changes, there will be an additional indentation level. That way, the changes on the different paths are easily grouped together visually.

  It is even possible to go past an ''Add'' change, in order to see if there has been a ''Delete'' change on that path, before
  that ''Add''. This mode is labeled ''Show only adds, moves and deletes''. The operation can be quite resource intensive and therefore take some time to display.

  Finally, there's a checkbox ''Show full log messages'', which controls whether the full content of the commit log message
  should be displayed for each change, or only a shortened version of it.

  == The Revision Log Information

  For each revision log entry, the following columns are displayed:
   1. The first column contains a pair of radio buttons and should be used
      for selecting the ''old'' and the ''new'' revisions that will be used for [#InspectingChangesBetweenRevisions viewing the actual changes].
   1. A color code (similar to the one used for the
      [TracChangeset#ChangesetHeader changesets]) indicates the kind of change.
      Clicking on this column refreshes the revision log so that it restarts
      with this change.
   1. The '''Revision''' number, displayed as `@xyz`.
      This is a link to the TracBrowser, using the displayed revision as the base line.
   Next to it, you can see a little "wheel" icon [[Image(htdocs:../common/changeset.png)]],  which is clickable and leads to the TracChangeset view for that revision.
   1. The '''Age'''/'''Date''' at which the change was made.
      Depending on your [/prefs/localization session preference], the date is displayed in either //Relative// or //Absolute// format.
    * //Relative// format shows the '''Age''': the time elapsed as the number of hours, days, weeks, months, or years.
    * //Absolute// format shows the '''Date''' of the revision as a datetime.
   1. The '''Author''' of the change.
   1. The '''Log Message''', which contains either the truncated or full commit
      log message, depending on the value of the ''Show full log messages''
      checkbox in the form above.

  == Inspecting Changes Between Revisions

  The ''View changes...'' buttons (placed above and below the list of changes, on the left side) will show the set of differences
  corresponding to the aggregated changes starting from the ''old'' revision (first radio-button) to the ''new'' revision (second
  radio-button), in the TracChangeset view.

  Note that the ''old'' revision doesn't need to be actually ''older'' than the ''new'' revision: it simply gives a base
  for the diff. It's therefore entirely possible to easily generate a ''reverse diff'', for reverting what has been done
  in the given range of revisions.

  Finally, if the two revisions are identical, the corresponding changeset will be shown. This has the same effect as clicking on the changeset number.

  == Alternative Formats

  === The !ChangeLog Text

  At the bottom of the page, there's a ''!ChangeLog'' link that will show the range of revisions as currently shown, but as a simple text, matching the usual conventions for !ChangeLog files.

  === RSS Support

  The revision log also provides an RSS feed to monitor the changes. To subscribe to an RSS feed for a file or directory, open its
  revision log in the browser and click the orange 'XML' icon at the bottom of the page. For more information on RSS support in Trac, see TracRss.

  ----
  See also: TracBrowser, TracChangeset


name: TracRoadmap
author: trac
text:
  = The Trac Roadmap
  [[TracGuideToc]]

  The roadmap provides a view on the [wiki:TracTickets ticket system] that helps planning and managing the future development of a project.

  == The Roadmap View

  A roadmap is a list of future milestones. The roadmap can be filtered to show or hide ''completed milestones'' and ''milestones with no due date''. In the case that both ''show completed milestones'' and ''hide milestones with no due date'' are selected, ''completed'' milestones with no due date will be shown.

  == The Milestone View

  A milestone is a future timeframe in which tickets are expected to be solved. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar. It is possible to further [trac:TracRoadmapCustomGroups customise the ticket grouping] and have multiple ticket statuses shown on the progress bar.

  It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to [wiki:TracQuery custom queries] listing corresponding tickets.

  == Roadmap Administration

  With appropriate permissions it is possible to add, modify and remove milestones using either the web interface (roadmap and milestone pages), web administration interface or by using `trac-admin`.

  == iCalendar Support

  The Roadmap supports the [https://www.ietf.org/rfc/rfc2445.txt iCalendar] format to keep track of planned milestones and related tickets from your favorite calendar software. Many calendar applications support the iCalendar specification including:
   * [https://www.apple.com/ical/ Apple iCal] for Mac OS X.
   * [https://www.mozilla.org/projects/calendar/ Mozilla Calendar], cross-platform.
   * [https://www.kde.org/applications/office/korganizer/ Korganizer], the calendar application of the [http://www.kde.org/ KDE] project.
   * [https://wiki.gnome.org/Apps/Evolution Evolution], a contact manager, address manager and calendar for Gnome.
   * [https://office.microsoft.com/en-us/outlook/ Microsoft Outlook] can also read iCalendar files and appears as a new static calendar in Outlook.
   * [https://www.google.com/calendar/ Google Calendar].
   * [http://chandlerproject.org Chandler], a personal and small-group task management and calendaring tool, Apache licensed and orphaned since 2009.

  To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied.

  For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself and associated with a milestone.

  More information about iCalendar can be found at [https://en.wikipedia.org/wiki/ICalendar Wikipedia].
  ----
  See also: TracTickets, TracReports, TracQuery, [trac:TracRoadmapCustomGroups]


name: TracRss
author: trac
text:
  = Using RSS with Trac
  [[TracGuideToc]]

  Several of the Trac modules support content syndication using the RSS ([https://en.wikipedia.org/wiki/RSS Really Simple Syndication]) XML format. RSS pushes out Trac updates whenever they occur and to whoever has subscribed to it. Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file.

  Trac supports RSS feeds in:

   * TracTimeline — Use the RSS feed to '''subscribe to project events'''. Monitor overall project progress in your favorite RSS reader.
   * TracTickets, TracReports, and TracQuery — Allows syndication of report and ticket query results. Be notified about important and relevant tickets.
   * TracBrowser and TracRevisionLog — Syndication of file changes. Stay up to date with changes to a specific file or directory.

  == How to access RSS data

  Where RSS is available in Trac you should find a small orange '''RSS''' icon, typically at the bottom of the page:
  {{{#!html
  <a rel="nofollow" style="padding-left: 20px; background: url(../../chrome/common/feed.png) left center no-repeat;  border: none;"><span style="color: #666;padding: 0 0 2px; font-size: 11px;">RSS feed</span></a>
  }}}
  Clicking the icon will access the RSS feed for that specific resource.

  '''Note:''' Different modules provide different data in their RSS feeds. Usually the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an ''alternate view of the data currently displayed''.

  Since Trac 1.0 an RSS feed can be retrieved from a Trac site that requires authentication. Hover over the RSS icon, right click and //copy link address//.

  == Links
   * ''Specifications:''
     * https://cyber.harvard.edu/rss/rss.html — RSS 2.0 Specification.

   * ''Multi-platform RSS readers:''
     * http://www.rssowl.org/ — Open source, Eclipse-based, RSS reader for Linux, Mac and Windows systems that supports https and authenticated feeds.

   * ''Linux/BSD/*n*x systems:''
     * http://liferea.sourceforge.net/ — Open source GTK2 RSS Reader for Linux.
     * [https://kde.org/applications/internet/org.kde.akregator Akregator] — Open source KDE RSS Reader, part of KDE-PIM.

   * ''Mac OS X systems:''
     * https://ranchero.com/netnewswire/ — An excellent RSS reader for Mac OS X, has both free and paid versions.
     * https://www.utsire.com/shrook/ — An RSS reader for Max OS X that supports https, even with self signed certificates, and authenticated feeds.
     * http://vienna-rss.sourceforge.net/ — Open source Feed Reader for Mac OS X with smart folders support.

   * ''Windows systems:''
     * http://www.rssreader.com/ — Free and powerful RSS Reader for MS Windows.
     * https://www.sharpreader.net/ — A free RSS Reader written in .NET for MS Windows.

   * ''Firefox:''
     * https://www.mozilla.org/products/firefox/ — Mozilla Firefox features plenty [https://addons.mozilla.org/en-US/firefox/search/?q=rss&appver=&platform= add-ons] for supporting RSS.

  ----
  See also: TracTimeline, TracQuery, TracReports, TracTickets, TracBrowser, TracRevisionLog


name: TracSearch
author: trac
text:
  = Using Search

  Trac has built-in search functionality to search for occurrences of keywords and substrings in wiki pages, tickets and changeset properties, such as author, revision and log messages.

  In addition to the [search: Search module], you will also find a small search field above the navigation bar. It provides convenient access to the search module from all pages.

  The search results show the most recent modifications ranked first.

  == Quick searches

  For quick access to project resources, the quick-search field at the top of every page can be used to enter a [TracLinks TracLink], which will take you directly to the resource identified by that link:

   * ![42] -- Opens change set 42
   * !#42 -- Opens ticket number 42
   * !{1} -- Opens report 1
   * /trunk -- Opens the browser for the `trunk` directory in the default repository
   * /repos1/trunk -- Opens the browser for the `trunk` directory in the `repos1` repository

  To disable the Quickjump feature for a keyword start the query with an exclamation mark (`!`): use `!TracGuide` to search for occurrences of the literal word !TracGuide.

  == Search TracLinks

  From the Wiki, it is possible to link to a specific search using `search:` links:
   * `search:?q=crash` will search for the string "crash"
   * `search:?q=trac+link&wiki=on` will search for "trac" and "link" in wiki pages only

  == Search Filters

  On the search page, pressing the modifier key while selecting a search filter will unselect all other search filters.

  ----
  See also: TracLinks, TracQuery


name: TracStandalone
author: trac
text:
  = Tracd

  Tracd is a lightweight standalone Trac web server.
  It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.

  == Pros

   * Fewer dependencies: You don't need to install apache or any other web-server.
   * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default
   * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).

  == Cons

   * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
   * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
     or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.

  == Usage examples

  A single project on port 8080. (http://localhost:8080/)
  {{{#!sh
   $ tracd -p 8080 /path/to/project
  }}}
  Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use the `--hostname` option.
  {{{#!sh
   $ tracd --hostname=localhost -p 8080 /path/to/project
  }}}
  With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
  {{{#!sh
   $ tracd -p 8080 /path/to/project1 /path/to/project2
  }}}

  You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the
  different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.

  An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
  {{{#!sh
   $ tracd -p 8080 -e /path/to
  }}}

  There is support for the HTTPS protocol (//Since 1.3.4//). Specify the path to the PEM certificate file and keyfile using the `--certfile` and `--keyfile` options. You can specify just the `--certfile` option if you have a [https://docs.python.org/2/library/ssl.html#combined-key-and-certificate combined key and certificate].

  To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.

  == Installing as a Windows Service

  === Option 1
  To install as a Windows service, get the [https://www.google.com/search?q=srvany.exe SRVANY] utility and run:
  {{{#!cmd
   C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
   reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd.exe\" <your tracd parameters>"
   net start tracd
  }}}

  {{{#!div style="border: 1pt dotted; margin: 1em;"
  **Attention:** Do not use `tracd.exe` directly.  Instead register `python.exe` directly with `tracd.exe` as a parameter.  If you use `tracd.exe`, it will spawn the python process without SRVANY's knowledge.  This python process will survive a `net stop tracd`.
  }}}

  If you want tracd to start automatically when you boot Windows, do:
  {{{#!cmd
   sc config tracd start= auto
  }}}

  The spacing here is important.

  {{{#!div
  Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above.  Navigate to:[[BR]]
  `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters`

  Three (string) parameters are provided:
  ||!AppDirectory ||C:\Python27\ ||
  ||Application ||python.exe ||
  ||!AppParameters ||scripts\tracd.exe -p 8080 ... ||

  Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point.
  (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.)
  }}}

  For Windows 7 User, srvany.exe may not be an option, so you can use [https://www.google.com/search?q=winserv.exe WINSERV] utility and run:
  {{{#!cmd
  "C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd.exe <your tracd parameters>"
  net start tracd
  }}}

  === Option 2

  Use [https://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [https://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.

  === Option 3

  also cygwin's cygrunsrv.exe can be used:
  {{{#!sh
  $ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
  $ net start tracd
  }}}

  == Using Authentication

  Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (`htpasswd` and `htdigest`) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without `htpasswd` or `htdigest`; see below for alternatives)

  {{{#!div style="border: 1pt dotted; margin: 1em"
  **Attention:** Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like `ext2` or `ext3` on Linux, or HFS+ on OSX).
  }}}

  Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line.

  The general format for using authentication is:
  {{{#!sh
   $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
  }}}
  where:
   * '''base_project_dir''': the base directory of the project specified as follows:
     * when serving multiple projects: ''relative'' to the `project_path`
     * when serving only a single project (`-s`): the name of the project directory
   Don't use an absolute path here as this won't work. ''Note:'' This parameter is case-sensitive even for environments on Windows.
   * '''password_file_path''': path to the password file
   * '''realm''': the realm name (can be anything)
   * '''project_path''': path of the project

   * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth.  Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.

  Examples:

  {{{#!sh
   $ tracd -p 8080 \
     --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
  }}}

  Of course, the password file can be be shared so that it is used for more than one project:
  {{{#!sh
   $ tracd -p 8080 \
     --auth="project1,/path/to/passwordfile,mycompany.com" \
     --auth="project2,/path/to/passwordfile,mycompany.com" \
     /path/to/project1 /path/to/project2
  }}}

  Another way to share the password file is to specify "*" for the project name:
  {{{#!sh
   $ tracd -p 8080 \
     --auth="*,/path/to/users.htdigest,mycompany.com" \
     /path/to/project1 /path/to/project2
  }}}

  === Basic Authorization: Using a htpasswd password file
  This section describes how to use `tracd` with Apache .htpasswd files.

    Note: On Windows It is necessary to install the [https://pypi.python.org/pypi/passlib passlib]
    package in order to decode some htpasswd formats. Only `SHA-1` passwords (since Trac 1.0)
    work without this module.

  To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
  {{{#!sh
   $ sudo htpasswd -c /path/to/env/.htpasswd username
  }}}
  then for additional users:
  {{{#!sh
   $ sudo htpasswd /path/to/env/.htpasswd username2
  }}}

  Then to start `tracd` run something like this:
  {{{#!sh
   $ tracd -p 8080 --basic-auth="project,/fullpath/environmentname/.htpasswd,realmname" /path/to/project
  }}}

  For example:
  {{{#!sh
   $ tracd -p 8080 --basic-auth="project,/srv/tracenv/testenv/.htpasswd,My Test Env" /path/to/project
  }}}
  ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).

  === Digest authentication: Using a htdigest password file

  If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [https://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.

  Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.

  === Generating Passwords Without Apache

  Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd. Windows Python can grok MD5 password hashes just fine and you should use MD5.

  Trac also provides `htpasswd` and `htdigest` scripts in `contrib`:
  {{{#!sh
  $ ./contrib/htpasswd.py -cb htpasswd user1 user1
  $ ./contrib/htpasswd.py -b htpasswd user2 user2
  }}}

  {{{#!sh
  $ ./contrib/htdigest.py -cb htdigest trac user1 user1
  $ ./contrib/htdigest.py -b htdigest trac user2 user2
  }}}

  ==== Using `md5sum`
  It is possible to use `md5sum` utility to generate digest-password file:
  {{{#!sh
  user=
  realm=
  password=
  path_to_file=
  echo ${user}:${realm}:$(printf "${user}:${realm}:${password}" | md5sum - | sed -e 's/\s\+-//') > ${path_to_file}
  }}}

  == Reference

  Here's the online help, as a reminder (`tracd -h` or `tracd --help`):
  {{{
  usage: tracd [-h] [--version] [-e PARENTDIR | -s]
               [-a DIGESTAUTH | --basic-auth BASICAUTH] [-p PORT] [-b HOSTNAME]
               [--protocol {http,https,scgi,ajp,fcgi}] [--certfile CERTFILE]
               [--keyfile KEYFILE] [-q] [--base-path BASE_PATH] [--http10 | --http11]
               [-r | -d] [--pidfile PIDFILE] [--umask MASK] [--group GROUP] [--user USER]
               [envs [envs ...]]

  positional arguments:
    envs                  path of the project environment(s)

  optional arguments:
    -h, --help            show this help message and exit
    --version             show program's version number and exit
    -e PARENTDIR, --env-parent-dir PARENTDIR
                          parent directory of the project environments
    -s, --single-env      only serve a single project without the project list
    -a DIGESTAUTH, --auth DIGESTAUTH
                          [projectdir],[htdigest_file],[realm]
    --basic-auth BASICAUTH
                          [projectdir],[htpasswd_file],[realm]
    -p PORT, --port PORT  the port number to bind to
    -b HOSTNAME, --hostname HOSTNAME
                          the host name or IP address to bind to
    --protocol {http,https,scgi,ajp,fcgi}
                          the server protocol (default: http)
    --certfile CERTFILE   PEM certificate file for HTTPS
    --keyfile KEYFILE     PEM key file for HTTPS
    -q, --unquote         unquote PATH_INFO (may be needed when using the ajp protocol)
    --base-path BASE_PATH
                          the initial portion of the request URL's "path"
    --http10              use HTTP/1.0 protocol instead of HTTP/1.1
    --http11              use HTTP/1.1 protocol (default)
    -r, --auto-reload     restart automatically when sources are modified
    -d, --daemonize       run in the background as a daemon
    --pidfile PIDFILE     file to write pid when daemonizing
    --umask MASK          when daemonizing, file mode creation mask to use, in octal
                          notation (default: 022)
    --group GROUP         the group to run as
    --user USER           the user to run as
  }}}

  Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.

  == Tips

  === Serving static content

  If `tracd` is the only web server used for the project,
  it can also be used to distribute static content
  (tarballs, Doxygen documentation, etc.)

  This static content should be put in the `$TRAC_ENV/htdocs` folder,
  and is accessed by URLs like `<project_URL>/chrome/site/...`.

  Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
  the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
  which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).

  === Using tracd behind a proxy

  In some situations when you choose to use tracd behind Apache or another web server.

  In this situation, you might experience issues with redirects, like being redirected to URLs with the wrong host or protocol. In this case (and only in this case), setting the `[trac] use_base_url_for_redirect` to `true` can help, as this will force Trac to use the value of `[trac] base_url` for doing the redirects.

  If you're using the AJP protocol to connect with `tracd` (which is possible if you have flup installed), then you might experience problems with double quoting. Consider adding the `--unquote` parameter.

  See also [trac:TracOnWindowsIisAjp], [trac:TracNginxRecipe].

  === Authentication for tracd behind a proxy
  It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in [trac:#9206].

  Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.

  First we bring tracd into Apache's location namespace.

  {{{#!apache
  <Location /project/proxified>
          Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
          Require ldap-user somespecificusertoo
          ProxyPass http://localhost:8101/project/proxified/
          # Turns out we don't really need complicated RewriteRules here at all
          RequestHeader set REMOTE_USER %{REMOTE_USER}s
  </Location>
  }}}

  Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
  {{{#!python
  from trac.core import *
  from trac.config import BoolOption
  from trac.web.api import IAuthenticator

  class MyRemoteUserAuthenticator(Component):

      implements(IAuthenticator)

      obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false',
                 """Whether the 'Remote-User:' HTTP header is to be trusted for user logins
                  (''since ??.??').""")

      def authenticate(self, req):
          if self.obey_remote_user_header and req.get_header('Remote-User'):
              return req.get_header('Remote-User')
          return None

  }}}

  Add this new parameter to your TracIni:
  {{{#!ini
  [trac]
  ...
  obey_remote_user_header = true
  ...
  }}}

  Run tracd:
  {{{#!sh
  tracd -p 8101 -s proxified --base-path=/project/proxified
  }}}

  Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_dir] and enable it in your global trac.ini.

  Global config (e.g. `/srv/trac/conf/trac.ini`):
  {{{#!ini
  [components]
  remote-user-auth.* = enabled
  [inherit]
  plugins_dir = /srv/trac/plugins
  [trac]
  obey_remote_user_header = true
  }}}

  Environment config (e.g. `/srv/trac/envs/myenv`):
  {{{#!ini
  [inherit]
  file = /srv/trac/conf/trac.ini
  }}}

  === Serving a different base path than /
  Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
  {{{#!sh
   $ tracd --base-path=/some/path
  }}}

  ----
  See also: TracInstall, TracCgi, TracModPython, TracGuide, [trac:TracOnWindowsStandalone#RunningTracdasservice Running tracd.exe as a Windows service]


name: TracSupport
author: trac
text:
  = Trac Support =

  Like most [https://opensource.org/ open source projects], Trac support is available primarily through the [trac:MailingList mailing list] and the [trac: project wiki]. Both are maintained by the Trac community. The [trac: project wiki] is the authoritative source for the TracGuide, consisting of the administrator and user guides for Trac.

  There is an [trac:IrcChannel IRC channel] where online users can help out. Much of the 'live' development discussions also happen there.

  You can search questions tagged with `trac` on [https://stackoverflow.com/questions/tagged/trac Stack Overflow].

  Before you start a new support query, make sure you have done the appropriate searching:
   * in the project's [trac:TracFaq FAQ]
   * in past messages to the [https://groups.google.com/group/trac-users Trac Users Mailing List]
   * in the Trac ticket system, using either a [trac:search:?q=&ticket=on&wiki=on full search] or a [trac:query: ticket query].

  Please '''don't''' create a ticket in trac.edgewall.org to ask a Trac support question. Only create a ticket when you face a ''real'' and ''new'' bug in Trac, and do so only after having read the [trac:NewTicketGuidelines NewTicketGuidelines]. The more a bug report or enhancement request complies with those guidelines, the higher the chances are that it will be fixed or implemented promptly!

  ----
  See also: [trac:MailingList], [trac:TracTroubleshooting], [trac:TracFaq], [trac:CommercialServices]


name: TracSyntaxColoring
author: trac
text:
  = Syntax Coloring of Source Code
  Trac supports language-specific syntax highlighting of source code within wiki formatted text in [WikiProcessors#CodeHighlightingSupport wiki processors] blocks and in the [TracBrowser repository browser]. Syntax coloring is provided using [http://pygments.org/ Pygments], which covers a wide range of programming languages and other structured texts, and is actively supported. If Pygments is not available, Trac will display the content as plain text.

  == About Pygments

  [http://pygments.org/ Pygments] is a highlighting library implemented in pure python, very fast, easy to extend and [http://pygments.org/docs/ well documented].

  The Pygments default style can specified in the [TracIni#mimeviewer-section mime-viewer] section of trac.ini. The default style can be overridden by setting a //Style// preference on the [/prefs/pygments preferences page].

  [http://pygments.org/docs/lexers/ Pygments lexer] options can be specified as [WikiProcessors WikiProcessor] arguments and defaults can be set in the [TracIni#pygments-lexer-section environment configuration].

  == Syntax Coloring Support

  === Supported languages

  The list of currently supported languages can be found on the [http://pygments.org/languages/ supported languages] page. The list represents the languages supported in the most recent version of Pygments, so the languages actually supported in your installation could differ if you have an older version installed. The listing of [http://pygments.org/docs/lexers/ supported lexers] provides additional information about the default mime type to keyword mappings.

  Explicit control of the mime type associated with a [WikiProcessors WikiProcessor] and file extension is available through the `mime_map` setting. For example, by default `.m` files are considered Objective-C files. In order to treat `.m` files as MATLAB files, add `text/matlab:m` to the [wiki:TracIni#mimeviewer-mime_map-option "[mimeviewer] mime_map"] option.

  If a mimetype property such as `svn:mime-type` is set to `text/plain`, there is no coloring even if file is known type like `java`.

  === Direct Rendering

  Rich content may be directly //rendered// instead of syntax highlighted. This usually depends on which auxiliary packages are installed and which components are activated in your setup. For example, a `text/x-rst` document will be rendered via `docutils` if it is installed and the `trac.mimeview.rst.ReStructuredTextRenderer` is not disabled. It will be syntax highlighted otherwise.

  Similarly, a document with the mimetype `text/x-trac-wiki` is rendered using the Trac wiki formatter, unless the `trac.mimeview.api.WikiTextRenderer` component is disabled. If you want to ensure that an HTML document gets syntax highlighted and not rendered, use the `text/xml` mimetype.

  HTML documents are directly rendered only if the `render_unsafe_html` settings are enabled in your TracIni file. See [TracIni#attachment-render_unsafe_content-option "[attachment] render_unsafe_content"], [TracIni#browser-render_unsafe_content-option "[browser] render_unsafe_content"] and [TracIni#wiki-render_unsafe_content-option "[wiki] render_unsafe_content"]. The setting is present in multiple sections because there are different security concerns depending on where the document comes from.

  === Known MIME types

  [[KnownMimeTypes]]

  ----
  See also: WikiProcessors, WikiFormatting, TracWiki, TracBrowser


name: TracTickets
author: trac
text:
  = The Trac Ticket System
  [[TracGuideToc]]

  As the central project management element of Trac, tickets can be used for '''project tasks''', '''feature requests''', '''bug reports''' and '''software support issues''', among others.

  As with the TracWiki, this subsystem has been designed to make user contribution and participation as simple as possible. Tickets can be edited, annotated, assigned, prioritized and discussed.

  [=#edit-permissions]
  The default installation doesn't permit to non-authenticated users ("anonymous" users) to change anything, even to comment on an issue, for obvious spam prevention reasons. Check the local contributing policy, or contact your local Trac administrator.

  == Ticket Fields

  A ticket contains the following information:

   * '''Summary''' — Simple text without WikiFormatting.
   * '''Description''' — The body of the ticket. Accepts WikiFormatting.
   * '''Reporter''' — The author of the ticket.
   * '''Type''' — The default types are `defect`, `enhancement` and `task`.
   * '''Component''' — The project module or subsystem that this ticket concerns.
   * '''Version''' — Version of the project that this ticket pertains to.
   * '''Keywords''' — Useful for searching and report generation.
   * '''Priority''' — The default priorities are `trivial`, `minor`, `major`, `critical` and `blocker`. A dropdown list when multiple priorities are defined.
   * '''Severity''' — Similar to Priority, but the distinction may be useful for some projects. No severities are defined by default, therefore the field will be hidden from the ticket form.
   * '''Milestone''' — Milestone in which the ticket will be resolved. A dropdown list.
   * '''Assigned to/Owner''' — Principal person responsible for handling the issue.
   * '''Cc''' — A comma-separated list of other users or email addresses to notify when changes are made to a ticket.
   * '''Resolution''' — Reason why a ticket was closed. Default values are `fixed`, `invalid`, `wontfix`, `duplicate`, `worksforme`.
   * '''Status''' — The statuses are defined in the [TracWorkflow#BasicTicketWorkflowCustomization ticket workflow]. For the default workflow the statuses are `new`, `assigned`, `accepted`, `closed` and `reopened`.

  '''Notes:'''
   - The type, [trac:TicketComponent component], [TracRoadmap milestone], version, priority, severity fields and resolution can be managed using [TracAdmin trac-admin] or !WebAdmin.

  == Changing and Commenting Tickets

  With appropriate permissions, tickets can be commented and ticket properties changed. When viewing a ticket, the history of changes will appear below the ticket properties box.

  By default an authenticated user can edit their own ticket comments. Users with `TICKET_EDIT_COMMENT` can edit any comment.

  Comment editing is meant for making small corrections to comments, like fixing formatting or spelling errors. For major edits, you should be adding a new comment instead. Editing a comment will not produce a new entry on [/timeline], while entering a new comment or other changes will do.

  All edits (field changes, new comments, comment edits) update the "last changed" time of the ticket.

  '''Note:'''
   - TracLinks and WikiFormatting can be used in the ticket description and comments. Use TracLinks to refer to other issues, changesets and files.

   - See TracNotification for how to configure email notifications on ticket changes.

   - See TracWorkflow for information about the state transitions (ticket lifecycle), and customization of the workflow.

  == Hiding Fields

  Many of the default ticket fields can be hidden from the ticket web interface by removing all the possible values through the !WebAdmin or using [TracAdmin trac-admin]. This only applies to drop-down lists: ''type'', ''priority'', ''severity'', ''component'', ''version'' and ''milestone''.

  == Adding Custom Fields

  Trac lets you add custom ticket fields. See TracTicketsCustomFields for more information.

  == Default Values for Drop-Down Fields

  The option selected by default for the various drop-down fields can be set in [TracIni trac.ini]. Refer to the values prefixed with `default_` in the [[TracIni#ticket-section|"[ticket]"]] section. The default value of several fields can also be set through the !WebAdmin.

  If any of these options are omitted, the default value will either be the first in the list, or an empty value when allowed. The [[TracIni#ticket-allowed_empty_fields-option|allowed_empty_fields]] option determines which fields may have an empty value.

  == Assign-to as Drop-Down List

  If the list of possible ticket owners is finite, you can change the ''assign-to'' ticket field from a text input to a drop-down list. This is done by setting the `restrict_owner` option of the `[ticket]` section in [TracIni trac.ini] to `true`. In that case, Trac will populate the list with all users who **have an authenticated session** and possess the `TICKET_MODIFY` [TracPermissions permissions].

  An authenticated session will be created the first time a user authenticates with the project. You can manually add an authenticated session using the ["TracAdmin#?session add" trac-admin] `session add` command. The `:1` suffix on the session id (i.e. username) is the key to creating an authenticated session:
  {{{#!sh
  trac-admin /path/to/projenv session add <sid>:1 [name] [email]
  }}}

  You may find the dropdown list is //overpopulated// with users that are no longer active in the project. Revoking authentication privileges will not remove the session data that is used to populate the dropdown list. The [TracAdmin trac-admin] command can be used to list and remove sessions:

   - List all sessions:
  {{{#!sh
  trac-admin /path/to/projenv session list
  }}}
   - Remove a session:
  {{{#!sh
  trac-admin /path/to/projenv session delete SID
  }}}

  Alternatively, you can just revoke `TICKET_MODIFY` from users that you don't want to be included in the list. However, that will not be possible if you've granted `TICKET_MODIFY` to all //anonymous// or //authenticated// users.

  '''Notes:'''
   - If you need more flexibility, then use subclass `ConfigurableTicketWorkflow` and override the `get_allowed_owners` method (see [trac:#12807 Trac ticket 12807]).

   - Activating this option may cause some performance degradation. Read more about this in the [trac:TracPerformance#Configuration Trac performance] page.

  == Preset Values for New Tickets

  To create a link to the new-ticket form filled with preset values, you need to call the `/newticket?` URL with `variable=value` separated by `&`. Possible variables are:

   * '''type''' — The type droplist.
   * '''reporter''' — Name or email of the reporter.
   * '''summary''' — Summary line for the ticket.
   * '''description''' — Long description of the ticket.
   * '''component''' — The component dropdown list.
   * '''version''' — The version dropdown list.
   * '''severity''' — The severity dropdown list.
   * '''keywords''' — The keywords or tags.
   * '''priority''' — The priority dropdown list.
   * '''milestone''' — The milestone dropdown list.
   * '''cc''' — The list of emails for notifying about the ticket change.

  Example: `[/newticket?summary=Compile%20Error&version=1.0&component=gui]`

  To set the ticket owner the workflow action may also need to be selected. For the [TracWorkflow#TicketCreateAction default workflow], the //create and assign// action can be selected with `action=create_and_assign` and the owner specified by assigning `action_create_and_assign_reassign_owner`. Alternatively, you could avoid needing to select the action by using the [TracWorkflow#BasicTicketWorkflowCustomization default attribute] to make //create and assign// the default action.

  For other custom workflow actions, determine the variable names by inspecting the `name` attribute of the //action// radio button and the //owner// input or select element.

  == Deleting Tickets #deleter

  Ticket delete and ticket change delete functions are enabled through an optional component. To enable the functionality edit the [TracIni#components-section "[components]"] section of TracIni:
  {{{#!ini
  [components]
  tracopt.ticket.deleter.* = enabled
  }}}

  The //Delete// buttons appears next to the //Reply// buttons in the ticket description and ticket change areas. `TICKET_ADMIN` permission is required for deleting tickets and ticket changes.

  Tickets and ticket changes can also be deleted using the TracAdmin `ticket remove` and `ticket remove_comment` commands.

  == Cloning Tickets #cloner

  The ticket clone function is enabled through an optional component. To enable the functionality edit the [TracIni#components-section "[components]"] section of TracIni:
  {{{#!ini
  [components]
  tracopt.ticket.clone.* = enabled
  }}}

  The //Clone// buttons appears next to the //Reply// buttons in the ticket description and ticket change areas. The ticket summary, description and properties are cloned, with minor modifications such as changing the ticket reporter to the currently authenticated user.

  ----
  See also: TracTicketsCustomFields, TracNotification, TracReports, TracQuery, TracRepositoryAdmin#CommitTicketUpdater


name: TracTicketsCustomFields
author: trac
text:
  = Custom Ticket Fields
  Trac supports adding custom, user-defined fields to the ticket module. With custom fields you can add typed, site-specific properties to tickets.

  == Configuration

  Configure custom ticket fields in the [TracIni#ticket-custom-section "[ticket-custom]"] section of trac.ini.

  The syntax of each field definition is:
  {{{
   FIELD_NAME = TYPE
   (FIELD_NAME.OPTION = VALUE)
   ...
  }}}

  The example below should help to explain the syntax.

  === Field Names
  A field name can only contain lowercase letters a-z, uppercase letters A-Z or digits 0-9, and must not start with a leading digit.

  The following field names are reserved and can not be used for custom fields:
  * cc
  * changetime
  * col
  * comment
  * component
  * desc
  * description
  * format
  * group
  * groupdesc
  * id
  * keywords
  * max
  * milestone
  * or
  * order
  * owner
  * page
  * priority
  * report
  * reporter
  * resolution
  * row
  * severity
  * status
  * summary
  * time
  * type
  * verbose
  * version

  === Available Field Types and Options

   * '''text''': A simple (one line) text field.
     * label: Descriptive label.
     * value: Default value.
     * order: Sort order placement relative to other custom fields.
     * max_size: Maximum allowed size in characters (//Since 1.3.2//).
     * format: One of:
       * `plain` for plain text
       * `wiki` for [WikiFormatting wiki formatted] content
       * `reference` to treat the content as a queryable value
       * `list` to interpret the content as a list of queryable values, separated by whitespace
     * ticketlink_query: Query for linkifying ticket values.
       Not applicable for format `plain` and `wiki`.
   * '''checkbox''': A boolean value check box.
     * label: Descriptive label.
     * value: Default value, 0 or 1.
     * order: Sort order placement.
     * ticketlink_query: Query for linkifying ticket values.
   * '''select''': Drop-down select box. Uses a list of values.
     * label: Descriptive label.
     * options: List of values, separated by '''|''' (vertical pipe).
     * value: Default value (one of the values from options).
     * order: Sort order placement.
     * ticketlink_query: Query for linkifying ticket values.
   * '''radio''': Radio buttons. Essentially the same as '''select'''.
     * label: Descriptive label.
     * options: List of values, separated by '''|''' (vertical pipe).
     * value: Default value, one of the values from options.
     * order: Sort order placement.
     * ticketlink_query: Query for linkifying ticket values.
   * '''textarea''': Multi-line text area.
     * label: Descriptive label.
     * value: Default text.
     * rows: Height in lines.
     * order: Sort order placement.
     * max_size: Maximum allowed size in characters (//Since 1.3.2//).
     * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting.
   * '''time''': Date and time picker. (//Since 1.1.1//)
     * label: Descriptive label.
     * value: Default date.
     * order: Sort order placement.
     * format: One of:
       * `relative` for relative dates.
       * `date` for absolute dates.
       * `datetime` for absolute date and time values.

  If the `label` is not specified, it will be created by capitalizing the custom field name and replacing underscores with whitespaces.

  Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`.

  For applicable fields, the `ticketlink_query` option
  overrides [[TracIni#query-ticketlink_query-option|"[query] ticketlink_query"]], and the format is the same as
  that option. When the `ticketlink_query` option
  is not specified, `[query]` `ticketlink_query` is used to
  linkify the field.

  === Sample Configuration

  {{{#!ini
  [ticket-custom]

  test_one = text
  test_one.label = Just a text box

  test_two = text
  test_two.label = Another text-box
  test_two.value = Default [mailto:joe@nospam.com owner]
  test_two.format = wiki

  test_three = checkbox
  test_three.label = Some checkbox
  test_three.value = 1

  test_four = select
  test_four.label = My selectbox
  test_four.options = one|two|third option|four
  test_four.value = two

  test_five = radio
  test_five.label = Radio buttons are fun
  test_five.options = |uno|dos|tres|cuatro|cinco
  test_five.value = dos

  test_six = textarea
  test_six.label = This is a large textarea
  test_six.value = Default text
  test_six.cols = 60
  test_six.rows = 30

  test_seven = time
  test_seven.label = A relative date
  test_seven.format = relative
  test_seven.value = now

  test_eight = time
  test_eight.label = An absolute date
  test_eight.format = date
  test_eight.value = yesterday

  test_nine = time
  test_nine.label = A date and time
  test_nine.format = datetime
  test_nine.value = in 2 hours
  }}}

  '''Note''': To make a `select` type field optional, specify a leading `|` in `fieldname.options` (e.g. `test_five`).

  === Reports Involving Custom Fields

  Custom ticket fields are stored in the `ticket_custom` table, not in the `ticket` table. So to display the values from custom fields in a report, you will need a join on the 2 tables. Let's use an example with a custom ticket field called `progress`.

  {{{#!sql
  SELECT p.value AS __color__,
     id AS ticket, summary, owner, c.value AS progress
    FROM ticket t, enum p, ticket_custom c
    WHERE status IN ('assigned') AND t.id = c.ticket AND c.name = 'progress'
  AND p.name = t.priority AND p.type = 'priority'
    ORDER BY p.value
  }}}
  '''Note''': This will only show tickets that have progress set in them. This is '''not the same as showing all tickets'''. If you created this custom ticket field ''after'' you have already created some tickets, they will not have that field defined, and thus they will never show up on this ticket query. If you go back and modify those tickets, the field will be defined, and they will appear in the query.

  However, if you want to show all ticket entries (with progress defined and without), you need to use a `JOIN` for every custom field that is in the query:
  {{{#!sql
  SELECT p.value AS __color__,
     id AS ticket, summary, component, version, milestone, severity,
     (CASE status WHEN 'assigned' THEN owner||' *' ELSE owner END) AS owner,
     time AS created,
     changetime AS _changetime, description AS _description,
     reporter AS _reporter,
     (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress
    FROM ticket t
       LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
       JOIN enum p ON p.name = t.priority AND p.type='priority'
    WHERE status IN ('new', 'assigned', 'reopened')
    ORDER BY p.value, milestone, severity, time
  }}}

  Note in particular the `LEFT OUTER JOIN` statement here.

  Note that option names in trac.ini are case-insensitive, so even if your option name includes uppercase characters:
  {{{#!ini
  [ticket-custom]
  Progress_Type = text
  }}}
  you must use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.

  ----
  See also: TracTickets, TracIni


name: TracTimeline
author: trac
text:
  = The Trac Timeline =
  [[TracGuideToc]]

  Trac's timeline feature provides a historic view of the project.

  Trac events are listed in chronological order, comprised of a brief description of each event and, if applicable, the person responsible for the change.

  The timeline lists these kinds of events:
   * '''Wiki page events''' — Pages created and edited
   * '''Ticket events''' — Tickets open/closed and updated
   * '''Source code changes ''' — Repository check-ins
   * '''Milestone events''' — Milestones completed

  Each event entry provides a hyperlink to the event, the author of the change, as well as a brief excerpt of the actual comment or text, if available. Plugins may provide additional events for the timeline.

  The displayed events can be filtered using the filters in the preferences panel:
   * ''View changes from'' — the date from which to start displaying events (current date if empty). Events that occurred after this date will not be shown, only those that occurred before the date.
   * ''and X days back'' — how many days backwards in time to get events.
   * ''done by'' — the author of an event. It accepts a space-separated list of authors for which events should be included. Alternatively, if the author names are prefixed by a `-` character, then the events having those authors will be excluded, and all the others included. Single or double quotes can be used for specifying author names containing space characters.
   * ''Changesets in all repositories'' — if you have more than one repository connected to your Trac project, you can also filter events from specific repositories.
   * ''Milestones completed'' — display or hide milestones reached.
   * ''Tickets opened and closed'' — display or hide ticket open or close events.
   * ''Ticket updates'' - display or hide ticket update events (if enabled by [TracIni#timeline-ticket_show_details-option "[timeline] ticket_show_details"]).
   * ''Wiki changes'' — display or hide Wiki change events.

  See !TracIni's [wiki:TracIni#timeline-section "[timeline] section"] for timeline configuration options. Plugins may provide additional filters for the timeline.

  == RSS Support ==

  The Timeline module supports subscription using RSS 2.0 syndication. To subscribe to project events, click the orange '''XML''' icon at the bottom of the page. See TracRss for more information on RSS support in Trac.

  ----
  See also: TracWiki, WikiFormatting, TracRss


name: TracUnicode
author: trac
text:
  = Unicode Support in Trac

  [[TracGuideToc]]

  Trac encodes all text using [wikipedia:UTF-8], including text in tickets and wiki pages. Internal processing of text uses true [wikipedia:Unicode] representations. As such, it supports the most commonly used character encodings.

  If the default encoding of your source code repository is not UTF-8, you can specify it in [TracIni#trac-default_charset-option "[trac] default_charset"]:
  {{{#!ini
  default_charset = gbk
  }}}

  Ensure that your [trac:DatabaseBackend database] stores its data in UTF-8, otherwise results may be unpredictable.

  To convert your database to UTF-8, the easiest way is to create a dump of the database, convert it into UTF-8, for example using [https://www.gnu.org/software/libiconv/documentation/libiconv/iconv.1.html iconv], and then re-import it.

  == Examples

  === Arabic

  تراك يقوم بحفظ كل الكلمات باستخدام صيغة UTF-8، بما في ذلك الكلمات المستخدمة في صفحات  التيكت والويكي.

  === Bulgarian

  Българският език работи ли?

  === Česky

  Čeština v kódování UTF-8, žádný problém.

  === Chinese

  Traditional: 繁體中文, 漢字測試

  Simplified: 简体中文，汉字测试

  === Croatian

  Ako podržava srpski i slovenski mora podržavati i Hrvatski - čćžšđ ČĆŽŠĐ.

  === Dutch

  Enquêtes in de privésfeer zijn altijd geëngageerd.

  === English

  Yes indeed, Trac supports English. Fully.

  === Français

  Il est possible d'écrire en Français : à, ç, û.

  === German

  Trac-Wiki muß auch deutsche Umlaute richtig anzeigen: ö, ä, ü, Ä, Ö, Ü; und das scharfe ß.

  === Greek

  Τα Ελληνικά υποστηρίζονται επαρκώς επίσης.

  === Hebrew

  אני יכול לאכול זכוכית וזה לא מזיק לי

  === Hindi

  अब हिन्दी में।

  === Hungarian

  Árvíztűrő tükörfúrógép.

  === Icelandic

  Ævar sagði við ömmu sína: Sjáðu hvað ég er stór!

  === Japanese

  漢字 ひらがな カタカナ ﾊﾝｶｸｶﾅ 日本語試験

  === Korean

  이번에는 한글로 써보겠습니다. 잘 보이나요? 한글.

  === Latvian

  Latviešu valoda arī strādā!

  === Lithuanian

  Sudalyvaukime ir mes. Ar veikia lietuviškos raidės? ąčęėįšųūž ĄČĘĖĮŠŲŪŽ Žinoma, kad veikia. Kas tie mes?

  === Persian (Farsi)

  این یک متن فارسی است ولی امکان نوشتن مستقیم فارسی نیست چون حالت متن از راست به چپ و جود ندارد برای فارسی نوشتن باید از HTML استفاده کنید.
  {{{
  #!html
  <div dir="rtl">
  }}}
  این نمونه یک متن از راست به چپ فارسی است که در HTML نوشته شده تا اعداد 12345 و حروف لاتین ABCDEF در محل خودشان نمایش داده شوند.
  {{{
  #!html
  </div>
  }}}

  === Polish

  Pchnąć w tę łódź jeża lub osiem skrzyń fig. Nocna gżegżółka zawsze dzienną przekuka.

  === Portuguese

  É possível guardar caracteres especias da língua portuguesa, incluindo o símbolo da moeda européia '€', trema 'ü', crase 'à', agudos 'áéíóú', circunflexos 'âêô', til 'ãõ', cedilha 'ç', ordinais 'ªº', grau '°¹²³'.

  === Russian

  Проверка русского языка: кажется работает. И буква "ё" есть.

  === Serbian

  Podržan, uprkos činjenici da se za njegovo pisanje koriste чак два алфабета.

  === Slovenian

  Ta suhi škafec pušča vodo že od nekdaj!

  === Spanish

  Esto es un pequeño texto en Español, donde el veloz murciélago hindú comía cardillo y kiwi.

  === Swedish

  Räven raskar över isen med luva på.

  === Thai

  Trac แสดงภาษาไทยได้อย่างถูกต้อง!

  === Ukrainian

  Перевірка української мови.

  === Urdu

  ٹریک اردو بھی سپورٹ کرتا ہے۔

  === Vietnamese

  Viết tiếng Việt cũng được.


name: TracUpgrade
author: trac
text:
  = Upgrade Instructions
  [[TracGuideToc]]
  [[PageOutline(2-4,,inline,unnumbered)]]

  == Instructions

  There are seven recommended steps for upgrading to a newer version of Trac:

  === 1. Check your plugins

  Check whether your plugins are compatible with the version of Trac that you are upgrading to. Obsolete plugins listed in the [#VersionSpecificSteps version specific steps] below should be uninstalled or disabled.

  If you are upgrading to a minor release, plugin compatibility is usually not a concern because the Trac API is normally unchanged.

  If your plugins are installed from [https://trac-hacks.org trac-hacks.org] you can check compatibility by looking for a tag on the project page corresponding to a major release (e.g. `1.4`). If you are unsure, you'll want to contact the plugin author or ask on the [trac:MailingList MailingList].

  If you are running several Trac plugins it is good to test the upgrade and plugin functionality in a staging instance of your site before upgrading your production instance. Remember, plugin authors are responsible for Trac version compatibility and plugins can interact in unexpected ways. Your Trac instance may have a unique combination of plugins and therefore it's advised that you do some verification testing when making any changes to your site.

  === 2. Bring your server off-line

  It is not a good idea to update a running server: the server processes may have parts of the current packages cached in memory, and updating the code will likely trigger [#ZipImportError internal errors].

  Although a database backup will be implicitly created by default when upgrading the environment, it is always a good idea to perform a full backup of the environment using the [TracBackup hotcopy] command before beginning. You may also wish to create a full backup of your server.

  === 3. Update Trac and dependencies #UpdatetheTracCode

  The packages are available through several channels, as described in [trac:TracDownload]. If your Trac instance was installed through an operating system package manager, proceed with the standard steps that are appropriate for your operating system package manager. If it was installed through a Windows installer, uninstall the old Trac package before installing new Trac package.

  If you are managing your Trac installation using command line tools, `pip` is the preferred tool to upgrade a Trac instance because it will uninstall the old version. The following command will upgrade your Trac installation using the package published to [https://pypi.python.org/pypi/Trac PyPI].

  {{{#!sh
  $ pip install --upgrade Trac
  }}}

  The upgrade command will give you the latest release of Trac. If instead you wish to upgrade to a different version, such as a minor release of Trac when there is a newer major release available, then specify the Trac version in the `pip` command.

  {{{#!sh
  $ pip install --upgrade Trac==1.4.1
  }}}

  You should also upgrade dependencies so they are compliant with the [TracInstall#Dependencies required versions].

  === 4. Upgrade the Trac Environment #UpgradetheTracEnvironment

  Environment upgrades are not necessary for minor version releases unless otherwise noted.

  On starting your web server after upgrading Trac, a message will be displayed for projects that need to be upgraded and the projects will not be accessible until the upgrade is run.

  The upgrade is run using a [TracAdmin trac-admin] command:
  {{{#!sh
  $ trac-admin /path/to/projenv upgrade
  }}}

  This command will not have any effect if the environment is already up-to-date.

  It is recommended that you set the [[TracIni#logging-log_level-option|log_level]] to `INFO` before running the upgrade. The additional information in the logs can be helpful in case something unexpected occurs during the upgrade.

  Note that a backup of your database will be performed automatically prior to the upgrade. The backup is saved in the location specified by [[TracIni#trac-backup_dir-option|backup_dir]].

  === 5. Update the Trac Documentation === #UpdatetheTracDocumentation

  By default, every [TracEnvironment Trac environment] includes a copy of the Trac documentation for the installed version. To keep the documentation in sync with the installed version of Trac, upgrade the documentation:
  {{{#!sh
  $ trac-admin /path/to/projenv wiki upgrade
  }}}

  Note that this procedure will leave your `WikiStart`, `InterMapTxt` and `SandBox` pages unaltered. Local changes to other pages that are distributed with Trac will be overwritten, however these pages are read-only by default for Environments created in Trac 1.3.3 and later.

  === 6. Refresh static resources

  If you have configured your web server to serve static resources directly (accessed using the `/chrome/` URL) then you will need to refresh them using the [TracInstall#MappingStaticResources deploy command]. The `deploy` command will extract static resources and CGI scripts (`trac.wsgi`, etc) from the new Trac version and plugins into `/deploy/path`.
  {{{#!sh
  $ trac-admin /path/to/env deploy /deploy/path
  }}}

  Before refreshing, it is recommended that you remove the directory in which your static resources are deployed. The directory location depends on the choice you made during installation. This cleanup is not mandatory, but makes it easier to troubleshoot issues as your installation is uncluttered by unused assets from a previous release. As usual, make a backup before deleting the directory.

  {{{#!div style="border: 1pt dotted; margin: 1em"
  **Note:** Some web browsers (IE, Opera) cache CSS and !JavaScript files, so you should instruct your users to manually erase the contents of their browser's cache. A forced refreshed (SHIFT + <F5>) should be sufficient.
  {{{#!comment
  Remove above note once #9936 is fixed.
  }}}
  }}}

  === 7. Steps specific to a given Trac version #VersionSpecificSteps

  ==== Upgrading from Trac 1.4 to 1.5 #to1.5

  ===== Python 2.7 no longer supported

  Upgrade Python to 3.5 or later.

  ==== Upgrading from Trac 1.2 to 1.4 #to1.4

  ===== Python 2.6 no longer supported

  Upgrade Python to 2.7, but not 3.0 or greater.

  ===== MySQL-python no longer supported

  [https://pypi.python.org/pypi/PyMySQL PyMySQL] is the supported MySQL database library, support for [https://pypi.python.org/pypi/MySQL-python MySQL-python] has been removed.

  ===== Obsolete Plugins

  Trac has added functionality equivalent to the following plugins:

  * [https://trac-hacks.org/wiki/DynamicVariablesPlugin DynamicVariablesPlugin]: dynamic variables are autocompleted
  * [https://trac-hacks.org/wiki/NavAddPlugin NavAddPlugin]: see TracNavigation
  * [https://trac-hacks.org/wiki/FlexibleAssignToPlugin FlexibleAssignToPlugin]: subclass `ConfigurableTicketWorkflow` and override `get_allowed_owners`
  * [https://trac-hacks.org/wiki/TracMigratePlugin TracMigratePlugin]: Use the `trac-admin` [TracAdmin#ChangingDatabaseBackend convert_db command]

  The plugins should be removed when upgrading Trac to 1.4.

  ===== Jinja2 is the new template engine

  Content is now generated by using the Jinja2 template
  engine. You should verify that your plugins are
  compatible with this change.

  If you customized the Trac templates, or the `site.html`
  template, you'll need to adapt that as well.
  (TODO: expand...) See [#CustomizedTemplates]. Email [TracNotification#CustomizingContent notification templates] also need to
  be adapted.

  ===== New permission policies for Wiki and Ticket realms

  Since 1.3.2 there are new permission policies for the ticket and wiki systems. `DefaultTicketPolicy` allows an authenticated user with `TICKET_APPEND` or `TICKET_CHPROP` to modify the description of a ticket they reported. It also implements the pre-1.3.2 behavior of allowing users to edit their own ticket comments. [#Newpermissionspolicyforread-onlywikipages ReadonlyWikiPolicy], added in 1.1.2, is renamed to `DefaultWikiPolicy`. The new permission policies can be easily replaced with alternate implementations if the default behavior is not desired.

  If `[trac] permission_policy` has the default value `ReadonlyWikiPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy`, then `DefaultWikiPolicy, DefaultTicketPolicy` should be automatically appended to the list when upgrading the environment:
  {{{#!ini
  [trac]
  permission_policies = DefaultWikiPolicy,
   DefaultTicketPolicy,
   DefaultPermissionPolicy,
   LegacyAttachmentPolicy
  }}}

  If other permission policies are enabled, `trac.ini` will need to be edited to add `DefaultWikiPolicy, DefaultTicketPolicy` to `permission_policies`. See [wiki:TracFineGrainedPermissions#DefaultWikiPolicyandDefaultTicketPolicy] for additional details on the proper ordering.

  ===== Description field added to ticket enums #enum-description-field

  The ticket enums now have a //description// field. An //ambiguous column name// error may be seen for reports that reference the `description` column of another table and join the `enum` table with that table (e.g. `ticket`, `component`). The reports {1}, {2}, {3}, {4}, {5}, {7}, and {8} are modified by an upgrade step to fix the issue, but the modification may not succeed if the default reports have been modified, in which case `upgrade` will output a message to the terminal instructing the user to modify the reports. User-created reports may also need to be modified.

  Reports that display the error need to be modified to prefix the `description` column with the appropriate table name or alias. For example, if the `ticket` table is aliased as `t` (`ticket t` or `ticket AS t`), replace `description` with `t.description` if the report should use the ticket's `description` column.

  ===== Removed `<repostype>` and `<repospath>` arguments from `trac-admin` `initenv` command

  The TracAdmin `initenv` command allowed the default repository to be specified using the third and fourth positional arguments of `initenv`:
  {{{#!sh
  initenv [<projectname> <db> [<repostype> <repospath>]]
  }}}

  The arguments were an artifact of Trac < 0.12, which only supported a single repository. Trac 0.12 and later supports multiple repositories, which can be specified at the time of environment creation using the `--inherit` and `--config` arguments. See the [TracEnvironment#SourceCodeRepository initenv documentation] for details on specifying source code repositories.

  ==== Upgrading from Trac 1.0 to 1.2 #to1.2

  ===== Python 2.5 no longer supported

  Upgrade Python to at least 2.6 or 2.7, but not 3.0 or greater.

  ===== Obsolete Plugins

  Trac has added functionality equivalent to the following plugins:
  * [https://trac-hacks.org/wiki/AdminEnumListPlugin AdminEnumListPlugin]
  * [https://trac-hacks.org/wiki/AttachmentNotifyPlugin AttachmentNotifyPlugin]: attachment notifications are sent in Trac 1.0.3 and later
  * [https://trac-hacks.org/wiki/DateFieldPlugin DateFieldPlugin]: see the **time** [TracTicketsCustomFields#AvailableFieldTypesandOptions custom field type]
  * [https://trac-hacks.org/wiki/FlexibleReporterNotificationPlugin FlexibleReporterNotificationPlugin]: [trac:CookBook/Notification/Subscriptions custom subscribers] can be implemented in the new extensible notification system
  * [https://trac-hacks.org/wiki/GroupBasedRedirectionPlugin GroupBasedRedirectionPlugin]: the default handler can set as a user preference
  * [https://trac-hacks.org/wiki/GroupingAssignToPlugin GroupingAssignToPlugin]: groups and permissions can be used in the [TracWorkflow#BasicTicketWorkflowCustomization set_owner] workflow attribute
  * [https://trac-hacks.org/wiki/LinenoMacro LinenoMacro]: see WikiProcessors#AvailableProcessors
  * [https://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin NeverNotifyUpdaterPlugin]: see [TracNotification#notification-subscriber-section notification subscribers]
  * [https://trac-hacks.org/wiki/QueryUiAssistPlugin QueryUiAssistPlugin]: see TracQuery#Filters.
  * [https://trac-hacks.org/wiki/TicketCreationStatusPlugin TicketCreationStatusPlugin]: see [#NewWorkflowActions]

  The plugins should be removed when upgrading Trac to 1.2.

  ===== New workflow actions #NewWorkflowActions

  The ticket creation step is controlled with a workflow action. The default workflow has `create` and `create_and_assign` actions. The `create` action will always be added when upgrading the database. The `create_and_assign` action will be added if the workflow has an //assigned// state. You may want to edit your workflow after upgrading the database to customize the actions available on the //New Ticket// page.

  ===== New permissions policy for read-only wiki pages

  Since 1.1.2 the read-only attribute of wiki pages is enabled and enforced only when `ReadonlyWikiPolicy` is in the list of active permission policies. If `[trac] permission_policy` has the default value `DefaultPermissionPolicy, LegacyAttachmentPolicy`, then `ReadonlyWikiPolicy` should be automatically appended to the list when upgrading the environment:
  {{{#!ini
  [trac]
  permission_policies = ReadonlyWikiPolicy,
   DefaultPermissionPolicy,
   LegacyAttachmentPolicy
  }}}

  If other permission policies are enabled, `trac.ini` will need to have `ReadonlyWikiPolicy` appended to the list of active `permission_policies`. See TracFineGrainedPermissions#ReadonlyWikiPolicy for additional details on the proper ordering.

  ===== Navigation Ordering Moved

  The mainnav and metanav configuration ordering have
  been moved from `[trac]` `mainnav` and `[trac]` `metanav` to the `[mainnav]` and `[metanav]` sections. The ordering is now specified using the `order` attribute as described in [TracNavigation#nav-order TracNavigation].

  The new configuration values will be written to trac.ini on upgrade, preserving the navigation order for the environment. You may need to edit trac.ini
  if you use a shared [TracIni#GlobalConfiguration global configuration].
  For example, if you wish to specify the navigation ordering for several environments in `global.ini`, you'll
  need to add the `[mainnav]` and `[metanav]` sections
  in that file and delete those sections from each
  environment's trac.ini.

  ==== Upgrading from Trac 0.12 to Trac 1.0 #to1.0

  ===== Python 2.4 no longer supported

  Upgrade Python to at least 2.5, but not 3.0.

  ===== Obsolete Plugins

  Trac has added functionality equivalent to the following plugins:

  * [https://trac-hacks.org/wiki/AnchorMacro AnchorMacro]
  * [https://trac-hacks.org/wiki/BatchModifyPlugin BatchModifyPlugin]
  * [https://trac-hacks.org/wiki/GitPlugin GitPlugin]
  * [https://trac-hacks.org/wiki/OverrideEditPlugin OverrideEditPlugin]
  * [https://trac-hacks.org/wiki/ProgressMeterMacro ProgressMeterMacro]

  The plugins should be removed when upgrading Trac to 1.0.

  ===== Subversion components not enabled by default for new installations

  The Trac components for Subversion support are no longer enabled by default. To enable the svn support, you need to make sure the `tracopt.versioncontrol.svn` components are enabled, for example by setting the following in the TracIni:
  {{{#!ini
  [components]
  tracopt.versioncontrol.svn.* = enabled
  }}}

  The upgrade procedure should take care of this and change the TracIni appropriately, unless you already had the svn components explicitly disabled.

  ===== Attachments migrated to new location #AttachmentsMigrated

  Another step in the automatic upgrade will change the way the attachments are stored. There have been reports that the attachment migration [#AttachmentsNotMigrated sometimes fails], so it's extra important that you [TracBackup backup your environment].

  In case the `attachments` directory contains some files which are //not// attachments, the last step of the migration to the new layout will not be completed: the deletion of the now unused `attachments` directory can't be done if there are still files and folders in it. You may ignore this error, but better to move them elsewhere and remove the `attachments` directory manually. The attachments themselves are now all located in your environment below the `files/attachments` directory.

  ===== Behavior of `[ticket] default_owner` changed

  Prior to 1.0, the owner field of new tickets always defaulted to `[ticket] default_owner` when the value was not empty. If the value was empty, the owner field defaulted to to the Component's owner. In 1.0 and later, the `default_owner` must be set to `< default >` to make new tickets default to the Component's owner. This change allows the `default_owner` to be set to an empty value if no default owner is desired.

  ==== Upgrading from older versions of Trac #OlderVersions

  For upgrades from versions older than Trac 0.12, refer first to [trac:wiki:0.12/TracUpgrade#SpecificVersions TracUpgrade for 0.12].

  For upgrades from versions older than Trac 0.10, refer first to [trac:wiki:0.10/TracUpgrade#SpecificVersions TracUpgrade for 0.10].

  == Known Issues

  === Customized Templates

  Trac supports customization of its templates by placing copies of the templates in the `<env>/templates` folder of your [TracEnvironment environment] or in a common location specified in the [TracIni#GlobalConfiguration  inherit.templates_dir] configuration setting. If you choose to customize the templates, be aware that you will need to repeat your changes on a copy of the new templates when you upgrade to a new release of Trac (even a minor one), as the templates will evolve. So keep a diff around.

  The preferred way to perform TracInterfaceCustomization is a custom plugin doing client-side !JavaScript transformation of the generated output, as this is more robust in case of changes: we usually won't modify an element `id` or change its CSS `class`, and if we have to do so, this will be documented in the [trac:TracDev/ApiChanges] pages.

  === !ZipImportError

  Due to internal caching of zipped packages, whenever the content of the packages change on disk, the in-memory zip index will no longer match and you'll get irrecoverable !ZipImportError errors. Better to anticipate and bring your server down for maintenance before upgrading.
  See [trac:#7014] for details.

  === Wiki Upgrade

  `trac-admin` will not delete or remove default wiki pages that were present in a previous version but are no longer in the new version.

  === Parent dir

  If you use a Trac parent env configuration and one of the plugins in one child does not work, none of the children will work.

  === Attachments not migrated #AttachmentsNotMigrated

  There have been reports that attachments are not [#AttachmentsMigrated migrated] when upgrading to Trac 1.0 or later. The cause of the issue has not yet been found. If you encounter this issue, see [https://trac.edgewall.org/wiki/TracFaq#Q:Attachmentsaremissingafterupgrade the FAQ] for a workaround and please report your findings to [trac:#11370].

  == Related topics

  === Upgrading Python

  Upgrading Python to a newer version will require reinstallation of Python packages: Trac itself of course, but also [TracInstall#Dependencies dependencies]. If you are using Subversion, you'll need to upgrade the [trac:TracSubversion Python bindings for SVN].



  -----
  See also: TracGuide, TracInstall


name: TracWiki
author: trac
text:
  = The Trac Wiki System =
  [[TracGuideToc]]

  Trac has a built-in wiki system which you can use for organizing knowledge and information in a very flexible way by [WikiNewPage creating pages] containing an intuitive and easy to learn textual markup. The wiki markup is used throughout Trac, so not only in [wiki:TitleIndex wiki pages], but also in [TracTickets ticket] description and comments, [TracChangeset version control] log messages, [TracRoadmap milestone] descriptions, [TracReports report] descriptions  and even in third-party extensions.
  It allows for formatted text and hyperlinks in and between all Trac modules.

  Editing wiki text is easy, as compared to complex markup languages like HTML, using any web browser and simple [WikiFormatting formatting]. The motivation for wiki markup is that HTML, with its large collection of nestable tags, is too complicated to allow fast-paced editing, and distracts from the actual content of the pages. Note that Trac also supports [WikiHtml HTML], [WikiRestructuredText reStructuredText] and [https://txstyle.org Textile] as alternative markup formats, which can be used in parts of a page, so called wiki blocks.

  The main goal of the wiki is to make editing text easy in order to ''encourage'' people to contribute to a project. Trac also provides a simple toolbar to make formatting text even easier, and supports the [http://universaleditbutton.org/Universal_Edit_Button universal edit button] of your browser.

  The wiki itself does not enforce any structure, but rather resembles a stack of empty sheets of paper, where you can organize information and documentation as you see fit, and later reorganize if necessary.
  As contributing to a wiki is essentially building hypertext, general advice regarding HTML authoring apply here as well.
  For example, the ''[https://www.w3.org/Provider/Style Style Guide for online hypertext]'' explains how to think about the [https://www.w3.org/Provider/Style/Structure.html overall structure of a work] and how to organize information [https://www.w3.org/Provider/Style/WithinDocument.html within each document]. One of the most important tips is to "make your HTML page such that you can read it, even if you don't follow any links".

  Learn more about:
   * WikiFormatting rules, including advanced topics like WikiMacros and WikiProcessors.
   * How to use WikiPageNames and other forms of TracLinks which are used to refer to any resource within Trac.

  If you want to practice editing, please use the SandBox. Note that not all Trac wiki pages are editable by anyone, this depends on the local policy; check with your Trac administrators.

  Before saving your changes, you can ''Preview'' the page or ''Review Changes'' you have made.
  You can get an automatic preview of the formatting as you type when you activate the ''Edit Side-by-side'' mode. There is a [wiki:TracIni#/auto_preview_timeout configurable delay] between when you make your edit and when the automatic preview will update.

  Some more information about wikis on the web:
   * A definition of [https://wikipedia.org/wiki/Wiki Wiki] according to Wikipedia.
   * The [http://c2.com/cgi/wiki?WikiHistory history] behind the original wiki.
   * A wiki page explaining [http://www.usemod.com/cgi-bin/mb.pl?WhyWikiWorks why wiki works].

  ----
  See also: TracGuide


name: TracWorkflow
author: trac
text:
  = The Trac Ticket Workflow System

  [[PageOutline(2-5,Contents,pullout)]]
  [[TracGuideToc]]
  The Trac ticket system provides a configurable workflow.

  == The Default Ticket Workflow

  When a new environment is created, a default workflow is configured in your trac.ini. This workflow is the basic workflow, as specified in [trac:source:branches/1.4-stable/trac/ticket/workflows/basic-workflow.ini basic-workflow.ini]:

  {{{#!Workflow width=700 height=300
  leave = * -> *
  leave.operations = leave_status
  leave.default = 1

  create = <none> -> new
  create.default = 1

  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner

  accept = new,assigned,accepted,reopened -> accepted
  accept.permissions = TICKET_MODIFY
  accept.operations = set_owner_to_self

  resolve = new,assigned,accepted,reopened -> closed
  resolve.permissions = TICKET_MODIFY
  resolve.operations = set_resolution

  reassign = new,assigned,accepted,reopened -> assigned
  reassign.permissions = TICKET_MODIFY
  reassign.operations = set_owner

  reopen = closed -> reopened
  reopen.permissions = TICKET_CREATE
  reopen.operations = del_resolution
  }}}

  == Additional Ticket Workflows

  There are example workflows provided in the Trac source tree, see [trac:source:branches/1.4-stable/contrib/workflow contrib/workflow] for `.ini` config sections. One of those may be a good match for what you want. They can be pasted into the `[ticket-workflow]` section of your `trac.ini` file. However, if you have existing tickets then there may be issues if those tickets have states that are not in the new workflow.

  Here are some [trac:WorkFlow/Examples diagrams] of the above examples.

  == Basic Ticket Workflow Customization

  '''Note''': Ticket "statuses" or "states" are not separately defined. The states a ticket can be in are automatically generated by the transitions defined in a workflow. Therefore, creating a new ticket state simply requires defining a state transition in the workflow that starts or ends with that state.

  In the `[ticket-workflow]` section of `trac.ini`, each entry is an action that may be taken on a ticket.
  For example, consider the `accept` action from `simple-workflow.ini`:

  {{{#!ini
  accept = new,accepted -> accepted
  accept.permissions = TICKET_MODIFY
  accept.operations = set_owner_to_self
  }}}

  The first line in this example defines the `accept` action, along with the states the action is valid in (`new` and `accepted`), and the new state of the ticket when the action is taken (`accepted`).

  The `accept.permissions` line specifies the permissions the user must have to use this action. [trac:ExtraPermissionsProvider] can define new permissions to be used here.

  The `accept.operations` line specifies changes that will be made to the ticket in addition to the status change when the action is taken.  In this case, when a user clicks on `accept`, the ticket owner field is updated to the logged in user.  Multiple operations may be specified in a comma separated list.

  The available operations are:
  - **del_owner** -- Clears the owner field.
  - **set_owner** -- Sets the owner to the selected or entered owner. Defaults to the current user. When `[ticket] restrict_owner = true`, the select will be populated with users that have `TICKET_MODIFY` permission and an authenticated session.
   - ''actionname''`.set_owner` may optionally specify a comma delimited list of users that will be used to populate the select, or a single user. Groups and permissions may also be included in the list //(Since 1.1.3)//. When groups or permissions are specified the select is populated with all members of the group or all users that possess the permission.
  - **set_owner_to_self** -- Sets the owner to the logged in user.
  - **may_set_owner** -- Sets the owner to the selected or entered owner. Defaults to the existing owner. //(Since 1.1.2)//.
  - **del_resolution** -- Clears the resolution field.
  - **set_resolution** -- Sets the resolution to the selected value.
   - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. The resolution(s) specified in this attribute must be defined in the database. Example:
   {{{#!ini
  resolve_new = new -> closed
  resolve_new.label = resolve
  resolve_new.operations = set_resolution
  resolve_new.permissions = TICKET_MODIFY
  resolve_new.set_resolution = invalid,wontfix
  }}}
  - **leave_status** -- Displays "leave as <current status>" and makes no change to the ticket.
  - **reset_workflow** -- Resets the status of tickets that are in states no longer defined.
  '''Note:''' Specifying conflicting operations, such as `set_owner` and `del_owner`, has unspecified results.

  The example that follows demonstrates the `.label` attribute. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`.

  {{{#!ini
  resolve_accepted = accepted -> closed
  resolve_accepted.label = resolve
  resolve_accepted.permissions = TICKET_MODIFY
  resolve_accepted.operations = set_resolution
  }}}

  The `.label` attribute is new in Trac 1.1.3 and is functionally the same as the `.name` attribute, which is now deprecated. If neither `.label` or `.name` is specified, the action will be presented to the user as //resolve accepted//, the underscores having been replaced by whitespace (//Since 1.1.3//).

  For actions that should be available in all states, `*` may be used in place of the state. The obvious example is the `leave` action:
  {{{#!ini
  leave = * -> *
  leave.operations = leave_status
  leave.default = 1
  }}}

  The transition to `*` (`-> *`) means the workflow operation determines the next status. The only configurable ticket workflow operation that determines the next status is `leave_status`. However, another workflow controller can operate on an action with new status `*` and determine the next status.

  This also shows the use of the `.default` attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest `.default` value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing `.default` values.
  If not specified for an action, `.default` is 0. The value may be negative.

  There is one hard-coded constraint to the workflow: tickets are expected to have a `closed` state. The default reports/queries treat any state other than `closed` as an open state.

  === Ticket Create Action

  The ticket create actions are specified by a transition from the special `<none>` state. At least one create action must be available to the user in order for tickets to be created. The create actions defined in the default workflow are:
  {{{#!ini
  create = <none> -> new
  create.default = 1

  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner
  }}}

  === Ticket Reset Action

  The special `_reset` action is added by default for tickets that are in states that are no longer defined. This allows tickets to be individually "repaired" after the workflow is changed, although it's recommended that the administrator perform the action by batch modifying the affected tickets. By default the `_reset` action is available to users with the `TICKET_ADMIN` permission and reset tickets are put in the //new// state. The default `_reset` action is equivalent to the following `[ticket-workflow]` action definition:

  {{{#!ini
  _reset = -> new
  _reset.label = reset
  _reset.operations = reset_workflow
  _reset.permissions = TICKET_ADMIN
  _reset.default = 0
  }}}

  Since [trac:milestone:1.0.3] the `_reset` action can be customized by redefining the implicit action. For example, to allow anyone with `TICKET_MODIFY` to perform the `_reset` action, the workflow action would need to be defined:

  {{{#!ini
  _reset = -> new
  _reset.label = reset
  _reset.operations = reset_workflow
  _reset.permissions = TICKET_MODIFY
  _reset.default = 0
  }}}

  == Workflow Visualization

  Workflows can be visualized by rendering them on the wiki using the [WikiMacros#Workflow-macro Workflow macro].

  Workflows can also be visualized using the `contrib/workflow/workflow_parser.py` script. The script outputs `.dot` files that [https://www.graphviz.org GraphViz] understands. The script can be used as follows (your install path may be different):

  {{{#!sh
  $ cd /var/local/trac_devel/contrib/workflow/
  $ ./showworkflow /srv/trac/PlannerSuite/conf/trac.ini
  }}}
  The script outputs `trac.pdf` in the same directory as the `trac.ini` file.

  == Example: Adding optional Testing with Workflow

  The following adds a `testing` action. When the ticket has status `new`, `accepted` or `needs_work`, you can choose to submit it for testing.  When it's in the testing status the user gets the option to reject it and send it back to `needs_work`, or pass the testing and send it along to `closed`. If they accept it, then it is automatically marked as `closed` and the resolution is set to `fixed`. Since all the old work flow remains, a ticket can skip this entire section.

  {{{#!ini
  testing = new,accepted,needs_work,assigned,reopened -> testing
  testing.label = Submit to reporter for testing
  testing.permissions = TICKET_MODIFY

  reject = testing -> needs_work
  reject.label = Failed testing, return to developer

  pass = testing -> closed
  pass.label = Passes Testing
  pass.operations = set_resolution
  pass.set_resolution = fixed
  }}}

  == Example: Add simple optional generic review state

  Sometimes Trac is used in situations where "testing" can mean different things to different people so you may want to create an optional workflow state that is between the default workflow's `assigned` and `closed` states, but does not impose implementation-specific details. The only new state you need to add for this is a `reviewing` state. A ticket may then be "submitted for review" from any state that it can be reassigned. If a review passes, you can re-use the `resolve` action to close the ticket, and if it fails you can re-use the `reassign` action to push it back into the normal workflow.

  The new `reviewing` state along with its associated `review` action looks like this:

  {{{#!ini
  review = new,assigned,reopened -> reviewing
  review.operations = set_owner
  review.permissions = TICKET_MODIFY
  }}}

  To integrate this with the default workflow, you also need to add the `reviewing` state to the `accept` and `resolve` actions:

  {{{#!ini
  accept = new,reviewing -> assigned
  […]
  resolve = new,assigned,reopened,reviewing -> closed
  }}}

  Optionally, you can also add a new action that allows you to change the ticket's owner without moving the ticket out of the `reviewing` state. This enables you to reassign review work without pushing the ticket back to the `new` status:

  {{{#!ini
  reassign_reviewing = reviewing -> *
  reassign_reviewing.label = reassign review
  reassign_reviewing.operations = set_owner, leave_status
  reassign_reviewing.permissions = TICKET_MODIFY
  }}}

  The full `[ticket-workflow]` configuration will be:

  {{{#!ini
  [ticket-workflow]
  create = <none> -> new
  create.default = 1
  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner
  accept = new,reviewing -> assigned
  accept.operations = set_owner_to_self
  accept.permissions = TICKET_MODIFY
  leave = * -> *
  leave.default = 1
  leave.operations = leave_status
  reassign = new,assigned,accepted,reopened -> assigned
  reassign.operations = set_owner
  reassign.permissions = TICKET_MODIFY
  reopen = closed -> reopened
  reopen.operations = del_resolution
  reopen.permissions = TICKET_CREATE
  resolve = new,assigned,reopened,reviewing -> closed
  resolve.operations = set_resolution
  resolve.permissions = TICKET_MODIFY
  review = new,assigned,reopened -> reviewing
  review.operations = set_owner
  review.permissions = TICKET_MODIFY
  reassign_reviewing = reviewing -> *
  reassign_reviewing.operations = set_owner, leave_status
  reassign_reviewing.label = reassign review
  reassign_reviewing.permissions = TICKET_MODIFY
  }}}

  == Advanced Ticket Workflow Customization

  If the customizations above do not meet your needs, you can extend the workflow with plugins. Plugins can provide additional operations for the workflow, like code review, or implement side-effects for an action, such as triggering a build, that may not be merely simple state changes. Look at [trac:source:branches/1.4-stable/sample-plugins/workflow sample-plugins/workflow] for a few examples to get started.

  But if even that is not enough, you can disable the !ConfigurableTicketWorkflow component and create a plugin that completely replaces it. See also the [https://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin], which provides additional operations.

  == Adding Workflow States to Milestone Progress Bars

  If you add additional states to your workflow, you may want to customize your milestone progress bars as well. See the [TracIni#milestone-groups-section "[milestone-groups]"] section.

  == Ideas for next steps

  Enhancement ideas for the workflow system should be filed as enhancement tickets against the [trac:query:?status=assigned&status=new&status=reopened&keywords=~workflow&component=ticket+system ticket system] component.  You can also document ideas on the [trac:TracIdeas/TracWorkflow TracIdeas/TracWorkflow] page.


