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 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. The format used in Context and Unified diffs allows to apply a patch, even though the line number mentioned for the hunk (patch terminology) is incorrect. In this case, when applying the patch, the algorithm scans both forwards and backwards for a set of lines matching the context given for the hunk.
   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 Apply Patch wizard will open.
   
   This can also be achieved by copying the patch contents to the clipboard and pasting it directly into the Package Explorer view by choosing Edit > Paste. In this case, you can skip the next step.
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. URL - the patch is located under the given URL. Warning: Make sure the URL you entered is valid and contains a proper patch. Otherwise you won't be able to apply it. Also, please keep in mind that applying a patch directly from a URL may take some time.
   4. 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 applies, only 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. There are two types of entries in the top pane: file changes and unmatched patch segments (known as 'hunk' in patch terminology).
   1. If one of more of the patch segments can be automatically applied to the file, the file will be shown with an incoming change indicator. You can inspect the change by double-clicking on the file.
   2. If one or more hunks cannot be automatically applied, the hunk entries will appear as children of the file in the top pane and a red exclamation mark indicates that there is a problem with a patch or hunk. You can inspect the hunk by double-clicking on it. You can then manually apply the hunk from the right pane to the file on the left. Saving from the left pane will update the parent file entry in the top pane but will not modify the file on disk. The file on disk is only modified when Finish is pressed. In order to apply the full patch successfully you will have to eliminate the problems (red exclamation marks) either by manually applying the patch segments, by excluding the patch segment from the operation by selecting Remove from the context menu or 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.

Patches can be applied by synchronizing them with a local content

To synchronize with a patch:

1. From the Team Synchronizing perspective select the Synchronize... action from the Synchronize button drop down.
2. Select Synchronize with Patch from the list of possible synchronization types and click Next.
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. URL - the patch is located under the given URL. Warning: Make sure the URL you entered is valid and contains a proper patch. Otherwise you won't be able to apply the patch. Also, please keep in mind that applying a patch directly from a URL may take some time.
   4. 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 applies, only 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. Optional Step: this step applies, only if your patch refers to projects that are inaccessible - if all projects from the patch are present in the workspace and are open, this page will be skipped. In the Inaccessible Projects page you can open any closed projects. Moreover, details about non-existing projects will be displayed. Projects that are closed or do not exist in the workspace cannot be patched.
6. On the final page, click Finish to preview patch changes in the Synchronize view.

Options for applying a patch

1. Go back to the first page of the Apply Patch 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 button to make the matching process independent from whitespace differences between the patch file and files in your workspace.
4. Adjust the Fuzz factor (patch terminology). This factor indicates the amount of hunk context lines to ignore. If the Fuzz factor value is zero all lines need to match. If the fuzz factor is greater than zero, for example 2, the first two context lines before the hunk and the last two context lines after the hunk are ignored. Click Guess to calculate the fuzz factor that allows the most hunks to be matched.
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, you can select another project in your workspace to apply the patch changes to. To do this, select a project in the top pane and select Move from the context menu. 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.
7. Use the Show Excluded option to show the hunks which you have already selected to not include in the patch.
8. When synchronizing with a patch, the options above are available in the Synchronize View's pull down menu. You can also switch between available models to get extra information about the changes being applied.

Related tasks

Related reference