Working with patches

Patches allow developers to share work without storing it in a repository. This is helpful when a developer wants to contribute to a project that is shared through a repository but does not have write access to the repository. In this situation, the developer can create a patch and either e-mail it to a developer who does have write access or attach it to a bug in the bug reporting system used by the project, depending on the process defined by the project. A developer that does have write access can then apply the patch to the project and commit the changes.

To create a patch from a CVS project:

1. Select the resource that contains the modifications to be included in the patch. Although this can be any folder, it is easiest to select the project itself because the patch must be applied to the same resource it is generated from. The patch should also be applied to the same file revisions that it is generated on so steps should be taken to ensure that the patch is applied to the same resource line-up (the easiest way to do this is to create the patch on top of a version).
2. From the popup menu, select Team > Create Patch.... The Create Patch wizard will open.
3. Choose where the patch should be saved:
   1. Save to Clipboard - this will place the patch on the clipboard so it can be pasted into a text editor such as an e-mail program.
   2. Save to File System - this will place the patch in the specified file in the local file system
   3. Save in Workspace - this will place the patch in the specified file inside one of the existing workbench projects.
   For small patches it may be reasonable to transfer the patch using the clipboard but in most cases the local file system in the best option to use. Click Next to configure how the patch is generated.
4. Choose how to configure the patch:
   1. Recurse into sub-folders - If disabled, only the direct children of the selection are included in the patch. Otherwise, all descendants are included.
   2. Include new files in patch - If disabled, only files that are under CVS version control are included. Otherwise, files that have been newly created but not added or ignored will also be included.
   3. Diff output format - Allows the choice of several common diff output formats. Unified is the format used by many patch application tools including Eclipse.
5. Click Finish.
6. Transfer the patch as appropriate for the project being patched.

To apply a patch:

1. Select the resource that the patch was generated on. This resource should contain the same file revisions as the line-up on which the patch was generated.
2. From the pop-up menu, select Team>Apply Patch.... The Resource Patcher wizard will open.
3. Indicate where the patch is to be found:
   1. File - the patch is in a file on the local file system. Either type in the full path to the file or use the Browse... button to find the file.
   2. Clipboard - the patch is on the clipboard. Warning: It is safer to use a file based patch. Line endings may not be handled properly if the clipboard is used and the patch was generated on a different platform (i.e. Linux vs. Windows).
   Click Next to see the effect of applying the patch.
4. The top pane of this page shows whether the patch could be successfully applied to files in your workspace. If you select a leaf item in the tree the bottom pane shows the part of the patch file (known as 'hunk' in patch terminology) in an easy to read side by side presentation. Note: The bottom pane does not show a preview of how resources in your workspace would look after applying the hunk. It just shows the contents of the patch file.
   1. A checked item indicates that a patch (or hunk) could be successfully applied to a workspace resource. You can exclude patches or individual hunks by unchecking them.
   2. A red exclamation mark indicates that there is a problem with a patch or hunk.
      This happens if the patch is not well formed or the revision of one or more files that the patch were generated on do not match the revisions that the patch is being applied to.
      You find the reason for the failure in parenthesis.

      In order to apply the full patch successfully you will have to eliminate the problems (red exclamation marks) and get checked items everywhere by tweaking the options on this wizard page (see 'Options' below).

5. If all is well, click Finish to apply the patch. The workspace will now contain outgoing changes for each file modified by the patch.

Options for applying a patch

1. Go back to the first page of the Resource Patcher wizard and select the correct resource to which the patch should be applied.
2. If a common prefix of the path names stored in the patch file doesn't match the path names in you current workspace, you can 'Ignore leading path name segments'.
3. Use the 'Ignore whitespace' option to make the matching process independent from whitespace differences between the patch file and files in your workspace.
4. Adjust the 'Maximum fuzz factor' (patch terminology). This factor determines how far from its original line a hunk is allowed to match. The default is two. So if a hunk does not match at the line given in the patch file, the Resource Patcher tries to match the hunk 'fuzz' number of lines before or after the position.
5. Use the 'Reverse patch' option for patch files that already have been applied to your workspace. This option is also useful to undo or redo a patch.

Team programming with CVS

Comparing resources

CVS