= Using a Subversion commit hook To Interact With TimingAndEstimationPlugin  =
== DOWNLOAD ==
 * ''' [browser:timingandestimationplugin/branches/trac0.10/scripts/trac-post-commit.py This plugin's version of the post-commit-hook for trac 10] '''
 * ''' [browser:timingandestimationplugin/branches/trac0.11/scripts/trac-post-commit.py This plugin's version of the post-commit-hook for trac 11] '''

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

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

 * 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}}}.

{{{
#!/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 parenthesis. :

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



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

'''Examples:'''

{{{ 
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 ==

This section contains requests for clarification.

=== 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, which seems to be more powerful, but does not support adding hours. It looks like this plugin provides a modified version that should be used instead, but that isn't clear above.