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. You can select resources that reside in multiple projects and at any level as the Create Patch wizard, when run in its default mode, knows how to create a multi-project patch. 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.
  4. You can preview and fine tune your patch selection by expanding the Resources tree presented in the Changes pane. Only those elements which are checked will be included in the patch. Click Next to configure how the patch is generated.
  5. Choose how to configure the patch:
    1. Diff output format - Allows the choice of several common diff output formats. Unified is the format used by many patch application tools including Eclipse.
    2. Patch Root - Allows you to specify at what level your patch is rooted at. The choices are Workspace, Project and Selection.

      Workspace allows you to include resources from multiple projects in your patch and is the default option. Workspace patches can be applied to any resource in the workspace - they contain enough information to allow the Apply Patch wizard to figure out which resources need to be patched.

      Project patches are rooted at the project level - which means they can only contain resources from one project and must be applied to the same project.

      Selection patches are rooted at whatever the selected resource is and must be applied to the same resource.
  6. Click Finish.
  7. 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).
    3. Workspace - the patch has been saved somewhere in the workspace.
    Click Next to see the effect of applying the patch.
  4. Optional Step: this step only applies if you have a patch rooted at the project or selection level - workspace rooted patches will automatically proceed to the Patch Preview Page. In the Patch Target Specification page, you should select the resource that is to act as the root of the patch.
  5. The patch preview page shows whether the patch could be successfully applied to files in your workspace. The top pane shows the list of changes contained in your patch. 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).

  6. 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

For getting successful matches of your patch file you have the following options:
  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 many lines from the top and bottom of the context will be ignored when locating a match The default is two.
  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.
  6. For Workspace patches, use the 'Retarget Patch' to select another project in your workspace to apply the patch changes to. To do this, select a project in the top pane and click on the Retarget Patch button. This will launch a dialog with a list of all available projects in your workspace. Select a project and click OK; the patch changes will be applied to your selected project.

Related concepts
Team programming with CVS

Related tasks
Comparing resources

Related reference
CVS