| 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] |
| |
| SEARCHBOX |
| --------- |