How to apply software patches

Check out the CytoscapePatchSubmission page for detailed instructions on how to create patch files.

Using command line tools

The tool used to apply patches is called patch. Type man patch for specific invocation details. The most important thing to understand about patches is that they need to be applied relative to where they were created. The patch command allows you to adjust the patch so that it matches your environment. The general process for applying a patch is as follows:

1. cd /your/source/directory

2. put the patch file (new_code.patch) in the current directory.

3. patch -pX < new_code.patch

The difficulty with patches lies in the -pX portion of the command. The X represents a digit and the digit tells you how many directories to strip off of the patch so that the patch becomes relative to your directory.

An example may help explain things. Consider the patch below, called new.patch, that adds a new method newMethod() to the Cytoscape.java file.

Index: src/cytoscape/Cytoscape.java
===================================================================
RCS file: /common/cvsdir5/cytoscape/src/cytoscape/Cytoscape.java,v
retrieving revision 1.129
diff -u -r1.129 Cytoscape.java
--- src/cytoscape/Cytoscape.java        24 May 2006 17:55:29 -0000      1.129
+++ src/cytoscape/Cytoscape.java        31 May 2006 01:15:59 -0000
@@ -1751,6 +1751,14 @@
                return sessionState;
        }

+
+       /**
+        * My new method.
+        */
+       public void newMethod() {
+               // do important things here
+       }
+
        /**
         * Clear all networks and attributes and start a
         * new session.

We'll assume that your working directory is /home/yourid/cytoscape.

Option #1 is to copy the patch file into your /home/yourid/cytoscape directory and run the command patch -p0 < new.patch. The -p0 indicates that no directories are stripped from the diff header which is this line:

Index: src/cytoscape/Cytoscape.java

You strip no directories because relative to your current directory /home/yourid/cytoscape the file Cytoscape.java that will be patched can be found in the src/cytoscape subdirectory. This patch was made from the /home/theirid/cytoscape directory, the patch sender's equivalent of yours, so you don't need to strip any directories.

Option #2 Assume that you've now copied the file to /home/yourid/cytoscape/src/cytoscape because you know that the patch is only for the file Cytoscape.java. In this case, the command you would run in patch -p2 < new.patch. The -p2 indicates that 2 directories are to be stripped. Because the patch was made in directory /home/theirid/cytoscape, but you are in /home/yourid/cytoscape/src/cytoscape, the header of the patch no longer accurately represents the location of the file relative to your current location. This means you need to strip off the src/cytoscape from the header so that the patch is once again correct relative to your current directory.

Using Eclipse