Last updated April 6, 2011.

A patch is a structured file that consists of a list of differences between one set of files and another. All code changes, additions, or deletions to Drupal core and contributed modules/themes between developers are done through patches.

Patches make development easier, because instead of supplying a replacement file, possibly consisting of thousands of lines of code, the patch includes only the exact changes that were made. In effect, a patch is a list of all the changes made to a file, which can be used to re-create those changes on another copy of that file.

Here is an example of what a patch looks like:

diff --git a/token_example/token_example.tokens.inc b/token_example/token_example.tokens.inc
index 585dcea..b06d9d6 100644
--- a/token_example/token_example.tokens.inc
+++ b/token_example/token_example.tokens.inc
@@ -13,8 +13,8 @@ function token_example_token_info() {
   // second is the user's default text format, which is itself a 'format' token
   // type so it can be used directly.

-  // This is a comment in the original file. It will be removed when the patch is applied.
+ // And here are lines we added when we were editing the file.
+ // They will replace the line above when the patch is applied.
$info['types']['format'] = array(
     'name' => t('Text formats'),
     'description' => t('Tokens related to text formats.'),

Here is a line by line breakdown of what this patch does:

  • This line explains which file is being modified; in this case, token_example/token_example.tokens.inc:
diff --git a/token_example/token_example.tokens.inc b/token_example/token_example.tokens.inc
index 585dcea..b06d9d6 100644
  • This line shows that the change is inside function token_example_token_info() around line 13:
@@ -13,8 +13,8 @@ function token_example_token_info() {
  • Remove this line (-):
-  // This is a comment in the original file. It will be removed when the patch is applied.
  • Add these lines (+). In this case, we're replacing the line of text with two new lines. Sometimes the change might simply be the addition of a period, or a grammatical correction:
+ // And here are lines we added when we were editing the file.
+ // They will replace the line above when the patch is applied.

The rest of the patch file merely provides context as to where the change lies, to help when applying patches.

Comments

RdeBoer’s picture

If you're new to this and wondering how to create a patch like the one shown above, you can use the diff -up command for this, on Unix-flavoured OS's, including Mac, or Cygwin on Windows.
In a Drupal context patches usually refer to changes you made in a local copy of a module checked out from the Git repository, see Making a Drupal patch with Git. However, if you're not comfortable with Git, but want to contribute and send the maintainer of a module a helpful patch, then you can use "diff", rather than "git diff".
Have copies of the original (say example.module.orig) and your modified version (example.module) ready and type:

  diff -up example.module.orig example.module > yourpatch.patch

This should produce a text file yourpatch.patch in a format similar to the example shown above.
When you submit your patch to a project issue queue it is customary to use a meaningful name for you patch file, one that incorporates project (i.e. "example"), issue description and number and comment number, using this format:

  diff -up example.module.orig example.module > example-[short-description]-[issue-number]-[comment-number].patch

It's always a good thing to obey Drupal coding-standards, especially when presenting someone with a patch. In order for the patch to be easily readable, make sure it doesn't contain tabs, trailing spaces or non-standard indentations, as these show up as spurious modifications and make it hard for the maintainer to figure out what your suggested code changes really are. There are a few options to the diff command that help, such as -w to ignore all white space in the generation of the .patch file and -d to produce a minimal diff.

  diff -upwd example.module.orig example.module > example-[short-description]-[issue-number]-[comment-number].patch