1Customizing the content and formatting of emails
2================================================
3
4Overloading template strings
5----------------------------
6
7The content of emails is generated based on template strings defined
8in ``git_multimail.py``. You can customize these template strings
9without changing the script itself, by defining a Python wrapper
10around it. The python wrapper should ``import git_multimail`` and then
11override the ``git_multimail.*`` strings like this::
12
13  import sys  # needed for sys.argv
14
15  # Import and customize git_multimail:
16  import git_multimail
17  git_multimail.REVISION_INTRO_TEMPLATE = """..."""
18  git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE
19
20  # start git_multimail itself:
21  git_multimail.main(sys.argv[1:])
22
23The template strings can use any value already used in the existing
24templates (read the source code).
25
26Using HTML in template strings
27------------------------------
28
29If ``multimailhook.commitEmailFormat`` is set to HTML, then
30git-multimail will generate HTML emails for commit notifications. The
31log and diff will be formatted automatically by git-multimail. By
32default, any HTML special character in the templates will be escaped.
33
34To use HTML formatting in the introduction of the email, set
35``multimailhook.htmlInIntro`` to ``true``. Then, the template can
36contain any HTML tags, that will be sent as-is in the email. For
37example, to add some formatting and a link to the online commit, use
38a format like::
39
40  git_multimail.REVISION_INTRO_TEMPLATE = """\
41  <span style="color:#808080">This is an automated email from the git hooks/post-receive script.</span><br /><br />
42
43  <strong>%(pusher)s</strong> pushed a commit to %(refname_type)s %(short_refname)s
44  in repository %(repo_shortname)s.<br />
45
46  <a href="https://github.com/git-multimail/git-multimail/commit/%(newrev)s">View on GitHub</a>.
47  """
48
49Note that the values expanded from ``%(variable)s`` in the format
50strings will still be escaped.
51
52For a less flexible but easier to set up way to add a link to commit
53emails, see ``multimailhook.commitBrowseURL``.
54
55Similarly, one can set ``multimailhook.htmlInFooter`` and override any
56of the ``*_FOOTER*`` template strings.
57