Gerrit uses Closure Templates (Soy) 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.
Compatibility Note: previously, Velocity Template Language (VTL) was used as the template language for Gerrit emails. VTL has now been deprecated in favor of Soy, but Velocity templates that modify text emails remain supported for now.
The default example templates reside under: '$site_path'/etc/mail and are terminated with the double extension .soy.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.
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.soy and ChangeFooter.soy below.)
Many types of Gerrit email message support HTML in addition to plain-text. Where both are supported, templates to control the HTML part have ...Html appended in their file names. For example, for “Abandoned” emails, the Abandoned.soy template determines the text part of the message, whereas AbandonedHtml.soy determines the HTML part.
The “Abandoned” templates will determine the contents of the email related to a change being abandoned. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
AddKey templates will determine the contents of the email related to SSH and GPG keys being added to a user account. This notification is not sent when the key is administratively added to another user account.
The ChangeFooter templates will determine the contents of the footer that will be appended to emails related to changes (all `ChangeEmail`s).
The ChangeSubject.soy template will determine the contents of the email subject line for ALL emails related to changes.
The Comment.soy template will determine the contents of the email related to a user submitting comments on changes. It is a ChangeEmail: see ChangeSubject.soy, ChangeFooter and CommentFooter.
The CommentFooter templates will determine the contents of the footer text that will be appended to emails related to a user submitting comments on changes. See ChangeSubject.soy, Comment and ChangeFooter.
The DeleteVote templates will determine the contents of the email related to removing votes on changes. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
The DeleteReviewer templates will determine the contents of the email related to a user removing a reviewer (with a vote) from a change. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
The Footer templates will determine the contents of the footer text appended to the end of all outgoing emails after the ChangeFooter and CommentFooter.
The Merged templates will determine the contents of the email related to a change successfully merged to the head. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
The NewChange templates 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.soy and ChangeFooter.
The RegisterNewEmail.soy template will determine the contents of the email related to registering new email accounts.
The ReplacePatchSet templates 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.soy and ChangeFooter.
The Restored templates will determine the contents of the email related to a change being restored. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
The Reverted templates will determine the contents of the email related to a change being reverted. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
The SetAssignee templates will determine the contents of the email related to a user being assigned to a change. It is a ChangeEmail: see ChangeSubject.soy and ChangeFooter.
Mail templates can access and display objects currently made available to them via the Soy context.
Be aware that modifying templates can cause them to fail to parse and therefore not send out the actual email.
All outgoing emails have the following variables available to them:
$email.settingsUrl
The URL to view the user’s settings in the Gerrit web UI.
$email.gerritHost
The name of the Gerrit instance.
$email.gerritUrl
The URL to the Gerrit web UI.
$messageClass
A String containing the messageClass.
Change related emails have the following template data available to them, in addition to what’s available to all outgoing emails.
$changeId
Id of the current change (a Change.Key).
$coverLetter
The text of the ChangeMessage.
$fromName
The name of the from user.
$email.unifiedDiff
The diff of the change.
$email.changeDetail
The details of the change, including the commit message.
$email.changeUrl
The URL to the change in the web UI.
$email.includeDiff
Whether the Gerrit instance is configured to include diffs in emails.
$change.subject
The subject of the current change.
$change.originalSubject
The subject corresponding to the first patch set of the current change.
$change.shortSubject
The subject limited to 72 characters, with an ellipsis if it exceeds that.
$change.ownerEmail
The email address of the owner of the change.
$branch.shortName
The name of the branch targeted by the current change.
$projectName
The name of this change’s project.
$shortProjectName
The project name with the path abbreviated.
$sshHost
SSH hostname for the Gerrit instance.
$patchSet.patchSetId
The current patch set number.
$patchSet.refname
The refname of the patch set.
Part of Gerrit Code Review
