Documentation/config-mail.txt - gerrit - Git at Google

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