tools/README.splitpatch

   1 Splitpatch is a program for splitting a set of diffs found in a single
   2 file according to the maintainers and then submitting the resulting
   3 patches.  Splitpatch does not require that the diffs were produced using
   4 Coccinelle.  Nevertheless, it is particularly useful when working with
   5 semantic patches, as these typically have an impact across the entire
   6 source code.  Splitpatch is completely Linux dependent, and relies on the
   7 Linux tools checkpatch.pl and get_maintainers.pl.  Splitpatch also relies
   8 on git send-email.  We have had to modify this program, to extract To
   9 information from each patch.  This modified version is currently called
  10 cocci-send-email.perl, and is installed with splitpatch.
  11
  12 1. Configuring splitpatch
  13
  14 Splitpatch needs some information about the environment, which it looks for
  15 in the file .splitpatch in your home directory.  An example
  16 configuration file, including the complete set of options, is as follows:
  17
  18 from = Julia Lawall <julia@diku.dk>
  19 git_tree = /var/linuxes/linux-next
  20 git_options = --cc=kernel-janitors@vger.kernel.org --suppress-cc=self
  21 prefix_before = /var/linuxes/linux-next
  22 prefix_after = /var/julia/linuxcopy
  23
  24 All of these options, and indeed the .splitpatch file itself, are
  25 optional, in at least some situations.  These are described in more detail
  26 as follows:
  27
  28 * from: Your patches will appear to come from this address.  Splitpatch
  29   makes three attempts to find the from address.  These are, in order of
  30   increasing priority: 1) The first Signed-off-by in the message file (the
  31   message file is defined below), 2) The from information in .git/config if
  32   the current directory or an ancestor of the current directory has a .git
  33   subdirectory, 3) The from information in ~/.splitpatch.
  34
  35 * git_tree: This is the directory containing the root of your Linux
  36   distribution.  This directory is expected to have a scripts subdirectory
  37   in which checkpatch.pl and get_maintainers.pl are found.  Splitpatch
  38   makes two attempts to find this information.  These are, in order of
  39   increasing priority: 1) The ancestor directory having .git as a
  40   subdirectory, 2) The git_tree information in ~/.splitpatch
  41
  42 * git_options: These are any options that you would always like to pass
  43   along to git.  This is only useful if you use splitpatch from a directory
  44   that is not part of your Linux source tree.  If splitpatch is used from
  45   within the Linux source tree, the git options found in .git/config will
  46   be used as well, regardless of whether or not some git_options are
  47   provided in ~/.splitpatch
  48
  49 * prefix_before, prefix_after: These are substrings to remove from the ---
  50   and +++ lines of each diff.  These options are probably not useful if you
  51   are managing your work using git.
  52
  53 Arguments for git send-email (cocci-send-email.perl) can also be passed on
  54 the splitpatch command line.  Anything that starts with - on the splitpatch
  55 command line is interpreted as an argument to git send-email
  56 (cocci-send-email.perl).  Finally, any further arguments can be passed to
  57 the generated command script (see send.cmd below).
  58
  59 2.  Using splitpatch
  60
  61 Beside any arguments for git send-email, the only argument to splitpatch is
  62 a file containing a sequence of diffs.  The diffs may be in any order and
  63 may be produced in any manner.  Each diff should start with the diff
  64 command, as generated by Coccinelle or by git diff.  The file should not
  65 contain diffstat information, as that will be computed.  The file may have
  66 any name, but we assume that it is called send.  If desired, this file name
  67 may have an extension, such as send.txt.
  68
  69 Given the file name send, splitpatch looks for a file send.msg in the same
  70 directory (send.txt would also cause splitpatch to look for send.msg).  The
  71 file send.msg should contain a subject line (which must be a single line),
  72 an optional cover letter, and a commit log message.  The sections should be
  73 separated by ---.  An example of a .msg file is as follows:
  74
  75 Eliminate memory leak
  76
  77 ---
  78
  79 These patches eliminate memory leaks in the uses of various functions.
  80
  81 ---
  82
  83 Allocated memory should be freed before dropping pointers to it.
  84
  85 Signed-off-by: Julia Lawall <julia@diku.dk>
  86
  87 ---
  88
  89 If send.msg has three sections, the first is the subject, the second is the
  90 cover letter, and the third is the commit log message.  If send.msg has
  91 only two sections, the first is the subject and the second is the commit
  92 log message.  In each section the first and last blank line, if any, is
  93 dropped.
  94
  95 Running splitpatch send generates a number of files.  These are send.cmd,
  96 send.cover (if a cover letter was specified), and sendn for various values
  97 of n starting with 1.
  98
  99 * send.cmd is the command line to use to send the patches.  Patches are
 100   sent as threaded messages if a cover letter is specified and unthreaded
 101   messages if no cover letter is specified.
 102
 103 * send.cover contains the cover letter in mailbox format.  The destination
 104   of the cover letter is the intersection of the destinations of all of the
 105   patches.  This will normally be at least linux-kernel@vger.kernel.org.
 106
 107 * send1 ... sendn contains the n patches.  Patches include the subject,
 108   commit log message, diffstat information, and the diff itself.  The
 109   destination of each patch is determined using get_maintainers.pl.  Each
 110   patch is checked using checkpatch.pl.  This may take a little time.
 111
 112 3.  Miscellaneous
 113
 114 Often, it may be useful to specialize the commit log messages of the
 115 individual patches in some way.  The sendn files may therefore be edited as
 116 needed.  Rerunning splitpatch will, however, overwrite the generated sendn
 117 files.  Indeed, there is no guarantee that the patches will continue to be
 118 distributed among the sendn files in the same way.