path: root/doc/README.MAIL

QUILT MAIL COMMAND
==================

The mail command starts up the system editor ($EDITOR, or vi if $EDITOR
is undefined) with an template in Internet Message Format (RFC 2822).
This template is used to generate an introduction, as well as one
message for each patch in the series file.  The template is used as
follows: The headers are used in each message generated, and modified as
required.  The template body is used only for the introduction.

In the template, the headers can be modified, additional headers added,
and unneeeded headers can be removed.  The template header also contains
a special Subject-Prefix header which defines a prefix to prefix each
subject header with.  The @num@ and @total@ macros in the Subject-Prefix
header are replaced with the patch number and the total number of
patches, respectively. The patch number @num@ is zero-padded to the
same width that @total@ has.

Each message is assigned a unique Message-Id header, and all messages
other than the introduction are made to refer to the introduction (using
a References header) for proper message threading in mail clients.
Patch filenames are stored in Content-Disposition headers so that mail
clients know the original filename.  The message timestamps in Date
headers in each message is incremented one second per message starting
from the timestamp of the introduction.

If a ~/.signature file exists, this file is appended to each message
generated.

Recipients and headers can be added, and existing headers can be
replaced, individually in each message based on the headers in the
introduction.  Quilt does not enforce a specific patch file format.
Instead, to customize the messages generated, a filter function called
quilt_mail_patch_filter may be defined in .quiltrc, or
/etc/quilt.quiltrc if no ~/.quiltrc exists.  This function is passed the
patch name as argument (without the $QUILT_PATCHES prefix). It shall
read the patch from standard input, and write a RFC 2822 message header
and the patch to standard output. Headers of the form ``Recipient-$X:
...'' denote recipients to be added to the $X header (for example,
``Recipient-Cc: agruen@suse.de'').  Headers of the form ``Replace-$X:
...'' specify that header $X is to be replaced by this header (for
eaxmple, ``Replace-Subject: Patch description''). All other headers
are appended to the existing headers.

A quilt_mail_patch_filter example is found in the example quilt.quiltrc.

Each recipient will occur in the resulting message only once. Duplicates
are filtered out. This happens as the headers are read, so the relative
order of the To, Cc, and Bcc headers should not be changed.

Recipients are checked for RFC 2822 conformance (at least that is the
intention; actually the checks are not perfect). This means that special
characters must be quoted, and 8-bit characters must be encoded. In
practice it probably makes little sense to use anything fancy right now;
this area still needs some work.  Character set recognition and proper
qualifying is also still missing.