git.oblomov.eu Git - git/blob - contrib/hooks/multimail/doc/customizing-emails.rst

   1 Customizing the content and formatting of emails
   2 ================================================
   3
   4 Overloading template strings
   5 ----------------------------
   6
   7 The content of emails is generated based on template strings defined
   8 in ``git_multimail.py``. You can customize these template strings
   9 without changing the script itself, by defining a Python wrapper
  10 around it. The python wrapper should ``import git_multimail`` and then
  11 override 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
  23 The template strings can use any value already used in the existing
  24 templates (read the source code).
  25
  26 Using HTML in template strings
  27 ------------------------------
  28
  29 If ``multimailhook.commitEmailFormat`` is set to HTML, then
  30 git-multimail will generate HTML emails for commit notifications. The
  31 log and diff will be formatted automatically by git-multimail. By
  32 default, any HTML special character in the templates will be escaped.
  33
  34 To use HTML formatting in the introduction of the email, set
  35 ``multimailhook.htmlInIntro`` to ``true``. Then, the template can
  36 contain any HTML tags, that will be sent as-is in the email. For
  37 example, to add some formatting and a link to the online commit, use
  38 a 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
  49 Note that the values expanded from ``%(variable)s`` in the format
  50 strings will still be escaped.
  51
  52 For a less flexible but easier to set up way to add a link to commit
  53 emails, see ``multimailhook.commitBrowseURL``.
  54
  55 Similarly, one can set ``multimailhook.htmlInFooter`` and override any
  56 of the ``*_FOOTER*`` template strings.