Splitpatch is a program for splitting a set of diffs found in a single
file according to the maintainers and then submitting the resulting
patches.  Splitpatch does not require that the diffs were produced using
Coccinelle.  Nevertheless, it is particularly useful when working with
semantic patches, as these typically have an impact across the entire
source code.  Splitpatch is completely Linux dependent, and relies on the
Linux tools checkpatch.pl and get_maintainers.pl.  Splitpatch also relies
on git send-email.  We have had to modify this program, to extract To
information from each patch.  This modified version is currently called
cocci-send-email.perl, and is installed with splitpatch.

1. Configuring splitpatch

Splitpatch needs some information about the environment, which it looks for
in the file .splitpatch in your home directory.  An example
configuration file, including the complete set of options, is as follows:

from = Julia Lawall <julia@diku.dk>
git_tree = /var/linuxes/linux-next
git_options = --cc=kernel-janitors@vger.kernel.org --suppress-cc=self
prefix_before = /var/linuxes/linux-next
prefix_after = /var/julia/linuxcopy

All of these options, and indeed the .splitpatch file itself, are
optional, in at least some situations.  These are described in more detail
as follows:

* from: Your patches will appear to come from this address.  Splitpatch
  makes three attempts to find the from address.  These are, in order of
  increasing priority: 1) The first Signed-off-by in the message file (the
  message file is defined below), 2) The from information in .git/config if
  the current directory or an ancestor of the current directory has a .git
  subdirectory, 3) The from information in ~/.splitpatch.

* git_tree: This is the directory containing the root of your Linux
  distribution.  This directory is expected to have a scripts subdirectory
  in which checkpatch.pl and get_maintainers.pl are found.  Splitpatch
  makes two attempts to find this information.  These are, in order of
  increasing priority: 1) The ancestor directory having .git as a
  subdirectory, 2) The git_tree information in ~/.splitpatch

* git_options: These are any options that you would always like to pass
  along to git.  This is only useful if you use splitpatch from a directory
  that is not part of your Linux source tree.  If splitpatch is used from
  within the Linux source tree, the git options found in .git/config will
  be used as well, regardless of whether or not some git_options are
  provided in ~/.splitpatch

* prefix_before, prefix_after: These are substrings to remove from the ---
  and +++ lines of each diff.  These options are probably not useful if you
  are managing your work using git.

Arguments for git send-email (cocci-send-email.perl) can also be passed on
the splitpatch command line.  Anything that starts with - on the splitpatch
command line is interpreted as an argument to git send-email
(cocci-send-email.perl).  Finally, any further arguments can be passed to
the generated command script (see send.cmd below).

2.  Using splitpatch

Beside any arguments for git send-email, the only argument to splitpatch is
a file containing a sequence of diffs.  The diffs may be in any order and
may be produced in any manner.  Each diff should start with the diff
command, as generated by Coccinelle or by git diff.  The file should not
contain diffstat information, as that will be computed.  The file may have
any name, but we assume that it is called send.  If desired, this file name
may have an extension, such as send.txt.

Given the file name send, splitpatch looks for a file send.msg in the same
directory (send.txt would also cause splitpatch to look for send.msg).  The
file send.msg should contain a subject line (which must be a single line),
an optional cover letter, and a commit log message.  The sections should be
separated by ---.  An example of a .msg file is as follows:

Eliminate memory leak

---

These patches eliminate memory leaks in the uses of various functions.

---

Allocated memory should be freed before dropping pointers to it.

Signed-off-by: Julia Lawall <julia@diku.dk>

---

If send.msg has three sections, the first is the subject, the second is the
cover letter, and the third is the commit log message.  If send.msg has
only two sections, the first is the subject and the second is the commit
log message.  In each section the first and last blank line, if any, is
dropped.

Running splitpatch send generates a number of files.  These are send.cmd,
send.cover (if a cover letter was specified), and sendn for various values
of n starting with 1.

* send.cmd is the command line to use to send the patches.  Patches are
  sent as threaded messages if a cover letter is specified and unthreaded
  messages if no cover letter is specified.

* send.cover contains the cover letter in mailbox format.  The destination
  of the cover letter is the intersection of the destinations of all of the
  patches.  This will normally be at least linux-kernel@vger.kernel.org.

* send1 ... sendn contains the n patches.  Patches include the subject,
  commit log message, diffstat information, and the diff itself.  The
  destination of each patch is determined using get_maintainers.pl.  Each
  patch is checked using checkpatch.pl.  This may take a little time.

3.  Miscellaneous

Often, it may be useful to specialize the commit log messages of the
individual patches in some way.  The sendn files may therefore be edited as
needed.  Rerunning splitpatch will, however, overwrite the generated sendn
files.  Indeed, there is no guarantee that the patches will continue to be
distributed among the sendn files in the same way.
