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

= Using a Subversion commit hook to interact with TimingAndEstimationPlugin

== Description

The {{{contrib/trac-post-commit-hook}}} script is a very convenient tool to interact with Trac's ticket system on commit. It allows to modify time tracking values and ticket state through special commit messages. This script references the TimingAndEstimationPlugin.

 * Copy {{{trac-post-commit-hook}}} into /usr/share/trac/contrib.
 * Create a script {{{hooks/post-commit}}} in your Subversion repository with the content below (modify '''TRAC_ENV''' to point to your local Trac project).
 * Set the executable bit: {{{chmod 755 hooks/post-commit}}}.

{{{#!sh
#!/bin/sh
REPOS="$1"
REV="$2"
LOG=`svnlook log -r $REV $REPOS`
AUTHOR=`svnlook author -r $REV $REPOS`
TRAC_ENV='/var/trac/test'

/usr/bin/python /usr/share/trac/contrib/trac-post-commit-hook \
  -p "$TRAC_ENV"  \
  -r "$REV"       \
  -u "$AUTHOR"    \
  -m "$LOG"
}}}

You can now use special keywords in your commit message to modify Trac tickets. The available commands are:

||refs #id||Adds a reference to the ticket's Changelog||
||re #id||Adds a reference to the ticket's Changelog||
||closes #id||Closes the ticket||
||fixes #id||Closes the ticket||

The time spent is specified in parentheses:

{{{
ex. re #853 (1) adds one hour to the ticket 853
}}}

See {{{contrib/trac-post-commit-hook}}} for details (after applying the patch).

== Download

This plugin's version of the post-commit-hook:
 * [browser:timingandestimationplugin/branches/trac0.10/scripts/trac-post-commit.py for Trac 0.10]
 * [browser:timingandestimationplugin/branches/trac0.11/scripts/trac-post-commit.py for Trac 0.11]

'''Note''': This information was taken from http://trac.edgewall.org/wiki/TimeTracking#UsingaSubversioncommithookoptional and modified to show how it works with this plugin.

== Examples

{{{#!sh
svn commit -m 'closes #1 (1), refs #2 (.5)  Added time tracking'
}}}

This closes ticket #1, increases the time spent by 1 hour. It adds an entry to the Changelog of ticket #2, increases the time spent by .5 hours.

== Gotchas

The script is pretty picky about what input it accepts.  I would suggest entering all of the commit hook commands on separate lines at the beginning of the message for best results.

== Open Questions

=== Relationship with normal ticket commit script

There is a commit hook trac-post-commit-hook that comes with Trac that enables closing tickets and adding references to tickets. This plugin provides a modified version that should be used instead, that also allows tracking hours.