Extension Point : IRepositoryChangeListener

Interface	IRepositoryChangeListener	Since	0.12
Module	trac.versioncontrol.api	Source	api.py​

The IRepositoryChangeListener allows components to listen for and to react to changes in repositories.

Purpose

Trac can be connected to Version Control systems to e.g. browse files, visualize changesets or revision logs. Plugins can hook into the version control module to trigger their own actions when changesets are added or modified.

The main purpose for this interface is to allow plugins to react to commits and trigger appropriate actions elsewhere (e.g. sending notifications or triggering changes via commands in the commit log messages etc.)

For example the CommitTicketUpdater allows referencing or closing tickets by embedding the ticket number in a commit log message.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The method changeset_added is called once for each new changeset committed to the repository.

For repositories that allow revision property changes (SVN), the method changeset_modified is called once for each changeset modified.

Note that the methods will not be called if the TracRepositoryAdmin is not configured correctly to call trac-admin $ENV changeset added/modified from the source control hooks.

Examples

Similarly to the CommitTicketUpdater mentioned above, you might want to close a milestone from a commit log message, e.g. when committing a tag or merging a branch. The following minimal example IRepositoryChangeListener implementation could implement such a feature:

from datetime import datetime
import re
from trac.core import Component, implements
from trac.ticket.model import Milestone
from trac.util.datefmt import utc
from trac.versioncontrol.api import IRepositoryChangeListener

class CommitMilestoneCloser(Component):
    implements(IRepositoryChangeListener)

    def changeset_added(self, repos, changeset):
        ref = re.search('complete milestone ([^\s]+)', changeset.message)
        if ref:
            milestone = Milestone(self.env, ref.group(1))
            milestone.completed = datetime.now(utc)
            milestone.update()

    def changeset_modified(self, repos, changeset, old_changeset):
        pass

Available Implementations

• CommitTicketUpdater

• ​th:FullTextSearchPlugin: Updates search index.
• ​th:MultiProjectCommitTicketUpdaterPlugin: Variation of CommitTicketUpdater that requires project prefixes.
• ​th:TracTicketChangesetsPlugin: Maintains a DB table that lists changesets referencing a ticket.
• ​th:CodeReviewerPlugin: Maintains a DB table that maps changesets to referenced tickets for code reviewing purposes.

Additional Information and References

• ​epydoc
• ​API Reference
• See trac.ticket.api.IMilestoneChangeListener, trac.ticket.api.ITicketChangeListener, trac.wiki.api.IWikiChangeListener, trac.attachment.IAttachmentChangeListener
• Version control cache database schema
• Related tickets:
  • Generic change listener replacement: #8834, #11148, #6543, ​Trac-dev:7737
  • #9263: Requested an implementation of a CommitMilestoneUpdater.
  • #8732: Requested an implementation of a CommitHoursUpdater for time tracking.
  • #731: Requested an implementation of a CommitNotificationSender.
  • #12898: ICachedRepositoryChangeListener for cached repository changes.

API History

• 0.12 introduced the interface (#7723, changeset:7961)