Introduction

The greatest strength of free software is that it allows collaboration and hyper specialization. The massive number of individuals who contribute to free software projects allows participants to focus on a specific technology, to specialize on that technology - it's theory, it's implementation and it's direction. This document is a very brief explanation of the patch system, a system used by programmers to allow collaboration on free software projects. The patch system is one of the technologies which was developed to enable hyper specialization with in the community. It plays a strong role in community development efforts, and therefor a basic understanding of it is critical for participating in development projects.

The patch systems works by distributing specially formatted text files called patches. A patch is a text file which describes the differences between a modified version of source code and the original source code. A patch exists in a format which allows it to be applied (or used to change) existing original copies of the source code to match the modified version. Patches are generated and applied by a set of two different GNU utilities. The diff utility is used to generated a patch file. The GNU utility patch is used to apply patch files. The patch file generated by the diff utility can then be distributed and applied to other copies of the original source code thus reducing the need to transmit full copies of the project source and the need to scan through the code to find and understand changes. These two utilities working together in the patch system significantly reduce the complexity of collaboration on software development.

Obviously though, the majority of the complexity in merging code lies in the design decisions inherent in that. Patch cannot eliminate that complexity. It is up to you, the developer, to attempt to reduce it as much as possible. To reduce the difficulty the maintainer will have in understanding and applying your patches take the following steps:

1. Discuss the changes with the maintainer before you make them if they are significant
2. Follow the coding style of the program you're submitting the patch for
3. Keep your patch simple, targeted at one design or code change or a small related group of them
4. Include a detailed description of the patch and an explanation of why you think it is needed with your patch submission
5. Include comments in your code and include your name and e-mail address in those comments

How To Do It

Original (helloworld-1.0/helloworld.c):

#include <stdio.h>

int main(void)
{
	prinf("Hello World!\n");
	return(0);
}

The first step is to make a copy of the source code to modify:

cp -R helloworld-1.0/ helloworld-1.0.new/

Next, you'll want to modify the copy of helloworld.c in the helloworld-1.0.new directory.

Modified Version (helloworld-1.0.new/helloworld.c):

#include <stdio.h>

int main(void)
{
	printf("Hello World and little green visitors!\n")
	return(0);
}

The next step (after testing the changes to the software) is to use diff to generate a patch file so that we can distribute out changes. When generating the patch file we invoke diff with the flags 'urN'. According to the diff manpage, these flags mean the following:

       -u     Use the unified output format.

       -r     When comparing directories, recursively compare any
              subdirectories found.

       -N
       --new-file
              In directory comparison, if a file is found in only
              one directory, treat it as present but empty in the
              other directory.

As you can see the use of these flags will allow diff to recursively compare all of the files under a pair of directories, assume that any new files should be taken into account as necessary additions, and produce a single patch file. The command we'll want to execute for our example is as follows:

diff -urN helloworld-1.0/ helloworld-1.0.new/ > helloworld.patch

That command will produce a patch file with the following contents:

diff -urN helloworld-1.0/helloworld.c helloworld-1.0.new/helloworld.c
--- helloworld-1.0/helloworld.c Sat Feb 19 13:11:35 2000
+++ helloworld-1.0.new/helloworld.c     Sat Feb 19 13:11:12 2000
@@ -2,6 +2,6 @@
 
 int main(void)
 {
-       prinf("Hello World!\n");
+       prinf("Hello World and little green visitors!\n");
        return(0);
 }

The format of the patch is obvious. You are referred to the patch utility source code if you want the details.

The patch can then be sent pack to the maintainer through e-mail, posted to a mailing list like the Linux Kernel Mailing List, or posted on a web or ftp site so that others can download it.

The patch can then be downloaded and applied to the original version of the code as shown in the following command:

patch -p0 < helloworld.patch

Here we tell patch with the 'p0' flag that the helloworld-1.0/ directory is in the same place on our system as it was on the system that the patch was generated on relative to the directory in which the patch was generated. Or in more simple terms, the helloworld-1.0/ directory is in our current working directory along with the patch file. The patch man page has additional information about the p flag and working with path locations.

That's all there is to it. Now go download some GPL'd software, fix some bugs, generate patches, and send them in to the maintainers.

Relevant Links

---

Last Updated: 2001.01.16.15.41.11
By: V. Alex Brennen [vab@cryptnet.net]
This document is Copyright 2000, 2001 by CryptNET. All Rights Reserved.
This document is licensed freely under the terms of the GPL.