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
To create a patch from a CVS project:
- 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).
- From the popup menu, select Team > Create Patch.... The Create
Patch wizard will open.
- Choose where the patch should be saved:
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.
- 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.
- Save to File System - this will place the patch in the specified
file in the local file system
- Save in Workspace - this will place the patch in the specified
file inside one of the existing workbench projects.
- 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.
- Choose how to configure the patch:
- 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.
- 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.
- Click Finish.
- Transfer the patch as appropriate for the project being patched.
To apply a patch:
- 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.
- From the pop-up menu, select Team > Apply Patch.... The Resource
Patcher wizard will open.
- Indicate where the patch is to be found:
Click Next to see the effect of applying the patch.
- 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.
- 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).
- Workspace - the patch has been saved somewhere in the workspace.
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.
- 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).
- 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.
- 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).
- 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:
Go back to the first page of the Apply Patch wizard and
select the correct resource to which the patch should be applied.
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.
Use the Ignore whitespace button to make the matching process
independent from whitespace differences between the patch file and files
in your workspace.
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.
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.
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.
Use the Show Excluded
option to show the hunks which you have already selected to not include in the patch.
Team programming with CVS