| :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. |
| |
| [NOTE] |
| The content of the templates at `'$site_path'/etc/mail/.*\.soy` are cached at |
| startup by Gerrit. If they are modified Gerrit needs to be restarted before the |
| changes takes effect. |
| |
| == 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 |
| --------- |