Patches are the preferred method for submitting changes to a FOSS project. This is because patches are a standard format and can be easily read and understood by developers familiar with the code base. A patch can include descriptions of multiple changes to multiple files, and this makes patches a great format for representing bug fixes or code enhancements that may touch many files within the larger project.
7.2.1. Example of a Simple Patch
In this example you generate a small change to a source code file to see how to create a patch. The file you start with is a simple Hello, World program hello.c written in C.
/* hello.c - a simple program to print out hello
* to the screen
*/
#include <stdio.h>
int main() {
printf("Hello, World.\n");
return 0;
}
That output is not too exciting -- instead change the punctuation to an exclamation point to really get some enthusiasm! The first step in making a change is to create a copy of the file you are working on. If you are working on code that is in a revision control system this step won't be necessary. For now, assume this code is not checked out from a repository (you practice creating patches using Subversion later in this chapter.)
Next, create a backup copy of the file hello.c and name it hello.c.punct so that you know the file is related to your punctuation change.
$ cp hello.c hello.c.punct
Next edit hello.c and leave the backup copy hello.c.punct as-is. Using your favorite editor, open hello.c and change the '.' in the printf statement to be a '!'. Save the file and exit out of the editor. Now generate a patch showing the change that was made. To do this, use the diff command. Since the unified diff format is considered by many to be easier to read, generate a patch in that format by passing the -u flag to the diff command. Run the following command to have the patch printed out to your screen:
$ diff -u hello.c.punct hello.c
--- hello.c.punct 2010-03-11 07:57:04.000000000 -0800
+++ hello.c 2010-03-11 07:58:54.000000000 -0800
@@ -5,6 +5,6 @@
#include <stdio.h>
int main() {
- printf("Hello, World.\n");
+ printf("Hello, World!\n");
return 0;
}
Examine the output from the diff command.
The first two lines represent the files that are being compared -- showing the file name as well as the last modified date.
Next are one or more hunks (pieces of a file) showing the differences between the files. In this case, you only have one change, so only one hunk is shown. Each hunk starts with the @@ text and numbers that represent the line numbers displayed in the change for the old (marked with a '-') and new (marked with a '+') files, respectively.
It then outputs the differences between the files. Since you used the -u flag to set the output to unified format, there are a number of lines shown that have not changed; these are output with a space in front of them.
Lines with a - in front of them have been removed from the first file.
Lines with a + in front of them are additions to the first file.
Notice that your one-line change is actually shown as the removal of an entire line and then an addition of a new, modified line.
When you ran the diff command you had it output to the screen. This can be useful when comparing things locally, but in order to share changes with others you should capture that output to a patch file. Use a simple shell redirect (>) to achieve this. In order to save the patch as hello-excitement.patch, the following command is used:
$ diff -u hello.c.punct hello.c > hello-excitement.patch
