| 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 <[email protected]> |
| 19 |
git_tree = /var/linuxes/linux-next |
| 20 |
git_options = [email protected] --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 <[email protected]> |
| 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 [email protected]. |
| 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. |