= Perforce Plugin for Trac =

[[TOC]]

== Description ==

'''IS THIS PROJECT DEAD??'''

This is a plugin for Trac (0.9, 0.10 or 0.11 (beta)) which enables [http://www.perforce.com/ Perforce]
to be used instead of [http://subversion.tigris.org/ Subversion] for the
[http://trac.edgewall.org/wiki/VersioningSystemBackend VersioningSystemBackend].

''(See Trac ticket [trac-ticket:257 #257] for more information)''

=== Features ===

The plugin now supports most of the features that the Subversion backend supports and
should be able to handle reasonably large Perforce repositories.

In particular the plugin so far supports:
 * Browsing source code in a Perforce repository via the TracBrowser
 * Specifying revisions using change number, file revision, date or label
 * Viewing the change history of a file or directory using TracRevisionLog
 * Performing [http://trac.edgewall.org/wiki/TracDiff diffs] between any 
   two files or two directories
 * Displaying submitted changes in the TracTimeline
 * Caching TracChangeset information in Trac's database
 * Using the TracSearch page to search change descriptions
 * Unicode enabled Perforce servers
 * Displaying Perforce file attributes
   (an undocumented Perforce feature similar to Subversion properties)
 * Efficient handling of large repository files.
 * Multi-threaded web servers
  (eg Apache with mod_python on Windows)

For a list of features that still need to be implemented see
[wiki:PerforcePlugin#Todo this list].

== History ==

The plugin was originally based on work from
[http://trac.edgewall.org/wiki/ChristianBoos Christian Boos]
on the [http://trac.edgewall.org/wiki/TracMercurial TracMercurial] plugin,
[http://www.jparks.net/blog/ Jason Parks] and [wiki:ttressieres Thomas Tressieres].

The plugin has recently undergone a major reworking by [wiki:lewisbaker Lewis Baker]
to try to improve handling of large repositories and large files.
The plugin was also ported to use [http://pyperforce.sourceforge.net/ PyPerforce]
to take advantage of its support for Python's `unicode` strings, multi-threading
and streaming of results.

== Download/Installation ==

The latest version (0.4.3) can be found [download:perforceplugin/trunk here] (for Trac 0.11 only).

=== Sources ===

The latest developmental version can be
[browser:perforceplugin/trunk browsed] or [download:perforceplugin/trunk downloaded].

The branch for trac-0.10 support can also be
[browser:perforceplugin/branches/trac-0.10 browsed] or
[download:perforceplugin/branches/trac-0.10 downloaded].

The branch for trac-0.9 support can also be
[browser:perforceplugin/branches/trac-0.9 browsed] or
[download:perforceplugin/branches/trac-0.9 downloaded].

Tagged releases can be [browser:perforceplugin/tags browsed here].

=== Requirements ===

 * [http://www.python.org/ Python] 2.4 or later
 * [http://pyperforce.sourceforge.net/ PyPerforce] 0.3a1 or later
 * [http://peak.telecommunity.com/PyProtocols.html PyProtocols] 0.9.3 or later
 * [http://peak.telecommunity.com/DevCenter/EasyInstall setuptools] 0.6c1 or later
 * Recent version of [http://trac.edgewall.org/ Trac] 0.10dev trunk
 * A working Trac installation
   (see [http://trac.edgewall.org/wiki/TracInstall TracInstall] for general information)
 * A [http://www.perforce.com/ Perforce] server
 
The PerforcePlugin has been tested against Perforce 2002.2, 2005.1 and 2005.2 servers.

=== Installation ===

 1. Download and install the requirements (see above).

 2. Build the .egg file (if building from source)[[BR]]
    Run:
{{{
$ python setup.py bdist_egg
}}}

 3. Install the `.egg` file
    * For per-project installation copy the `.egg` file to the `<TRAC_ENV>/plugins` directory.
    * For a global installation[[BR]]
      Run:
{{{
$ easy_install path/to/TracPerforce-0.4.3-py2.4.egg
}}}
      Or:
{{{
$ python setup.py install
}}}

=== Configuring Trac ===

You need to edit your [http://projects.edgewall.com/trac/TracIni <TRAC_ENV>/conf/trac.ini] file.

In the `[trac]` section you need to add:
{{{
[trac]
repository_type = perforce
repository_dir = /

[perforce]
port = perforce:1666
user = p4trac
password = secret
unicode = 0
}}}


One recommended Perforce configuration is to add a user with read access
and a login with no expiry, then setup your Trac configuration with this user
and use the Perforce ticket as the `password`.

If you installed trac globally you also need to enable the PerforcePlugin
in the `[components]` section:
{{{
[components]
p4trac.* = enabled
}}}

Finally, restart your Trac web server.

==== Note ====

Loading a page that uses the plugin for the first time can take
a long time while the plugin populates the initial changeset cache,
depending on the size of the Perforce repository.[[BR]]
See #630 for more info.

== Bugs/Feature requests ==

Existing bugs and feature requests for the PerforcePlugin are
[report:9?COMPONENT=PerforcePlugin here].

If you have an issues, create a
[http://trac-hacks.org/newticket?component=PerforcePlugin&owner=lewisbaker new ticket].

=== Todo ===

This is a brief list of some of the future work that needs to be done.

 * Replication of Trac tickets to Perforce jobs
   (ala [http://www.perforce.com/perforce/products/p4dti.html P4DTI]) (#625)
 * Add support for Trac 0.11 (#2338)
 * Add a `'fixes'` property to changesets that lists tickets/jobs fixed
   by that change. (#628)
 * Detect `'move'` file actions (ie `'copy'` and `'delete'` of same file) (#626)
 * Detect `'move'` and `'copy'` of entire directories (#627)
 * Add an `'integrations'` property to changesets/files that lists integrated
   revisions merged in that revision (#629)
 * Fix 'created_rev' to report the revision of last `'edit'`,
   skipping 'copy' or 'move' revisions (#633)
 * Better support for detecting modified change descriptions and updating
   changeset cache (use "p4 logger"?).
 * Per-user authentication and authorisation (#635)
 * Auto-detection of Unicode Perforce servers (#634)

== Recent Changes ==

[[ChangeLog(perforceplugin, 3)]]


== Feedback ==

[[Poll(Are you using perforce plugin?; Yes, it's usefull.; No, it's useless.; No, I don't need it.; I can't get the thing to work!)]]


== Contributors ==

Thanks to:
 * [http://projects.edgewall.com/trac/wiki/ChristianBoos Christian Boos]
 * [http://www.jparks.net/blog Jason Parks]
 * [http://www.hidheadlightkit.com Hid Kit]
 * [http://www.costumesdelux.com/halloween-costumes Halloween Costumes]
 * kristjan@ccpgames.com
 * kenjin@clazzsoft.com
 * [wiki:ttressieres Thomas Tressieres]
 * [wiki:lewisbaker Lewis Baker]

== Alternative ==

Alternatively, trac can access to Perforce through a git wrapper. Here's roughly what you need to do:
 1. Install and set up a git-p4 repository: [http://linux.lsdev.sil.org/wiki/index.php/Using_git-p4#git-p4 download], [https://git.wiki.kernel.org/index.php/Git-p4_Usage HowTo1], [http://linux.lsdev.sil.org/wiki/index.php/Using_git-p4 HowTo2]
 1. Install GitPlugin and use the git repository you set up above as your new Trac repository.
 1. Create a minutely cronjob that executes "git p4 rebase" for your repository.