201 lines
6.3 KiB
Plaintext
201 lines
6.3 KiB
Plaintext
= 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`.
|
|
|
|
=== AddKey.vm
|
|
|
|
The `AddKey.vm` template 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.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`.
|
|
|
|
=== DeleteVote.vm
|
|
|
|
The `DeleteVote.vm` template will determine the contents of the email related
|
|
to removing votes on changes. It is a `ChangeEmail`: see `ChangeSubject.vm`
|
|
and `ChangeFooter.vm`.
|
|
|
|
=== DeleteReviewer.vm
|
|
|
|
The `DeleteReiewer.vm` template 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.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`.
|
|
|
|
=== 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
|
|
---------
|