| 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`. | |
| CommitMessageEdited.vm | |
| ~~~~~~~~~~~~~~~~~~~~~~ | |
| The `CommitMessageEdited.vm` template will determine the contents of the email | |
| related to a user editing the commit message through the Gerrit UI. It is a | |
| `ChangeEmail`: see `ChangeSubject.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`. | |
| See Also | |
| -------- | |
| * link:http://velocity.apache.org/[velocity] | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] |