| :linkattrs: | |
| = Gerrit Code Review - Mail Templates | |
| Gerrit uses link:https://developers.google.com/closure/templates/[Closure Templates,role=external,window=_blank] | |
| (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. Support for VTL has now been removed | |
| in favor of Soy, and Velocity templates that modify text emails are no longer | |
| supported. | |
| == Template Locations and Extensions | |
| 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. | |
| == 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.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. | |
| === Abandoned.soy and AbandonedHtml.soy | |
| 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.soy and AddKeyHtml.soy | |
| 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. | |
| === ChangeFooter.soy and ChangeFooterHtml.soy | |
| The ChangeFooter templates will determine the contents of the footer that will | |
| be appended to emails related to changes (all `ChangeEmail`s). | |
| === ChangeSubject.soy | |
| The `ChangeSubject.soy` template will determine the contents of the email | |
| subject line for ALL emails related to changes. | |
| === Comment.soy | |
| 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. | |
| === CommentFooter.soy and CommentFooterHtml.soy | |
| 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. | |
| === DeleteKey.soy and DeleteKeyHtml.soy | |
| DeleteKey templates will determine the contents of the email related to SSH or GPG keys | |
| being deleted from a user account. This notification is not sent when the key is | |
| administratively deleted from another user account. | |
| === DeleteVote.soy and DeleteVoteHtml.soy | |
| 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. | |
| === DeleteReviewer.soy and DeleteReviewerHtml.soy | |
| 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. | |
| === Footer.soy and FooterHtml.soy | |
| The Footer templates will determine the contents of the footer text appended to | |
| the end of all outgoing emails after the ChangeFooter and CommentFooter. | |
| === HttpPasswordUpdate.soy and HttpPasswordUpdateHtml.soy | |
| HttpPasswordUpdate templates will determine the contents of the email related to adding, | |
| changing or deleting the HTTP password on a user account. | |
| === Merged.soy and MergedHtml.soy | |
| 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. | |
| === NewChange.soy and NewChangeHtml.soy | |
| 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. | |
| === RegisterNewEmail.soy and RegisterNewEmailHtml.soy | |
| Those templates will determine the contents of the email related to registering | |
| new email accounts. | |
| === ReplacePatchSet.soy and ReplacePatchSetHtml.soy | |
| 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. | |
| === Restored.soy and RestoredHtml.soy | |
| 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. | |
| === Reverted.soy and RevertedHtml.soy | |
| 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. | |
| === SetAssignee.soy and SetAssigneeHtml.soy | |
| 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 Variables and Methods | |
| Mail templates can access and display objects currently made available to them | |
| via the Soy context. | |
| === Warning | |
| Be aware that modifying templates can cause them to fail to parse and therefore | |
| not send out the actual email. | |
| === All OutgoingEmails | |
| 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 Emails | |
| 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.shortOriginalSubject:: | |
| + | |
| The original 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. | |
| $instanceAndProjectName:: | |
| + | |
| The Gerrit instance name, followed by the short project name | |
| $addInstanceNameInSubject:: | |
| + | |
| Whether the instance name should be included in the email subject. | |
| $sshHost:: | |
| + | |
| SSH hostname for the Gerrit instance. | |
| $patchSet.patchSetId:: | |
| + | |
| The current patch set number. | |
| $patchSet.refname:: | |
| + | |
| The refname of the patch set. | |
| $patchSetInfo.authorName:: | |
| + | |
| The name of the author of the patch set. | |
| $patchSetInfo.authorEmail:: | |
| + | |
| The email address of the author of the patch set. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |