Gerrit Code Review - Mail Templates

Gerrit uses velocity templates for the bulk of the standard mails it sends out. There are builtin default templates which are used if they are not overridden. These defaults are also provided as examples so that administrators may copy them and easily modify them to tweak their contents.

Template Locations and Extensions:

The default example templates reside under: '$site_path'/etc/mail and are terminated with the double extension .vm.example. Modifying these example files will have no effect on the behavior of Gerrit. However, copying an example template to an equivalently named file without the .example extension and modifying it will allow an administrator to customize the template.

Supported Mail Templates:

Each mail that Gerrit sends out is controlled by at least one template. These are listed below. Change emails are influenced by two additional templates, one to set the subject line, and one to set the footer which gets appended to all the change emails (see ChangeSubject.vm and ChangeFooter.vm below.)

Abandoned.vm

The Abandoned.vm template will determine the contents of the email related to a change being abandoned. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

ChangeFooter.vm

The ChangeFooter.vm template will determine the contents of the footer text that will be appended to emails related to changes (all `ChangeEmail`s).

ChangeSubject.vm

The ChangeSubject.vm template will determine the contents of the email subject line for ALL emails related to changes.

Comment.vm

The Comment.vm template will determine the contents of the email related to a user submitting comments on changes. It is a ChangeEmail: see ChangeSubject.vm, ChangeFooter.vm and CommentFooter.vm.

CommentFooter.vm

The CommentFooter.vm template will determine the contents of the footer text that will be appended to emails related to a user submitting comments on changes. See ChangeSubject.vm, Comment.vm and ChangeFooter.vm.

Footer.vm

The Footer.vm template will determine the contents of the footer text appended to the end of all outgoing emails after the ChangeFooter and CommentFooter.

Merged.vm

The Merged.vm template will determine the contents of the email related to a change successfully merged to the head. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

MergeFail.vm

The MergeFail.vm template will determine the contents of the email related to a failure upon attempting to merge a change to the head. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

NewChange.vm

The NewChange.vm template will determine the contents of the email related to a user submitting a new change for review. This includes changes created by actions made by the user in the Web UI such as cherry picking a commit or reverting a change. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

RegisterNewEmail.vm

The RegisterNewEmail.vm template will determine the contents of the email related to registering new email accounts.

ReplacePatchSet.vm

The ReplacePatchSet.vm template will determine the contents of the email related to a user submitting a new patchset for a change. This includes patchsets created by actions made by the user in the Web UI such as editing the commit message, cherry picking a commit, or rebasing a change. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

Restored.vm

The Restored.vm template will determine the contents of the email related to a change being restored. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

Reverted.vm

The Reverted.vm template will determine the contents of the email related to a change being reverted. It is a ChangeEmail: see ChangeSubject.vm and ChangeFooter.vm.

Mail Variables and Methods

Mail templates can access and display objects currently made available to them via the velocity context. While the base objects are documented here, it is possible to call public methods on these objects from templates. Those methods are not documented here since they could change with every release. As these templates are meant to be modified only by a qualified sysadmin, it is accepted that writing templates for Gerrit emails is likely to require some basic knowledge of the class structure to be useful. Browsing the source code might be necessary for anything more than a minor formatting change.

Warning

Be aware that modifying templates can cause them to fail to parse and therefore not send out the actual email, or worse, calling methods on the available objects could have internal side effects which would adversely affect the health of your Gerrit server and/or data.

All OutgoingEmails

All outgoing emails have the following variables available to them:

$email: A reference to the class constructing the current OutgoingEmail. With this reference it is possible to call any public method on the OutgoingEmail class or the current child class inherited from it.
$messageClass: A String containing the messageClass.
$StringUtils: A reference to the Apache StringUtils class. This can be very useful for formatting strings.

Change Emails

All change related emails have the following additional variables available to them:

$change: A reference to the current Change object.
$changeId: Id of the current change (a Change.Key).
$coverLetter: The text of the ChangeMessage.
$branch: A reference to the branch of this change (a Branch.NameKey).
$fromName: The name of the from user.
$projectName: The name of this change’s project.
$patchSet: A reference to the current PatchSet.
$patchSetInfo: A reference to the current PatchSetInfo.