| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Working with patches</title> |
| </HEAD> |
| |
| <BODY BGCOLOR="#ffffff"> |
| <H1>Working with patches</H1> |
| |
| <p>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.</p> |
| <H2>To create a patch from a CVS project:</H2> |
| <ol> |
| <li>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).</li> |
| <li>From the popup menu, select <b>Team > Create Patch...</b>. The Create |
| Patch wizard will open.</li> |
| <li>Choose where the patch should be saved: |
| <ol type="a"> |
| <li><i>Save to Clipboard</i> - this will place the patch on the clipboard |
| so it can be pasted into a text editor such as an e-mail program.</li> |
| <li><i>Save to File System</i> - this will place the patch in the specified |
| file in the local file system</li> |
| <li><i>Save in Workspace</i> - this will place the patch in the specified |
| file inside one of the existing workbench projects.</li> |
| </ol>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. </li> |
| <li>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 <b>Next</b> to configure how the patch is generated.</li> |
| <li>Choose how to configure the patch: |
| <ol type="a"> |
| <li><i>Diff output format</i> - Allows the choice of several common diff |
| output formats. <i>Unified</i> is the format used by many patch application |
| tools including Eclipse.</li> |
| <li><i>Patch Root</i> - Allows you to specify at what level your patch is rooted at. The choices |
| are <i>Workspace</i>, <i>Project</i> and <i>Selection</i>.<br> |
| <br><i>Workspace</i> allows you to include resources from multiple projects in your patch and is the <em>default</em> 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.<br> |
| <br><i>Project</i> 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.<br> |
| <br><i>Selection</i> patches are rooted at whatever the selected resource is and must be applied to the same resource. |
| </li> |
| </ol> |
| </li> |
| <li>Click <b>Finish</b>. </li> |
| <li>Transfer the patch as appropriate for the project being patched.</li> |
| </ol> |
| <H2>To apply a patch:</H2> |
| <ol> |
| <li>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.</li> |
| <li>From the pop-up menu, select <b>Team>Apply Patch...</b>. The Resource |
| Patcher wizard will open.</li> |
| <li>Indicate where the patch is to be found: |
| <ol type="a"> |
| <li><i>File</i> - the patch is in a file on the local file system. Either |
| type in the full path to the file or use the <b>Browse...</b> button to |
| find the file.</li> |
| <li><i>Clipboard</i> - the patch is on the clipboard. <b>Warning:</b> 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).</li> |
| <li><i>Workspace</i> - the patch has been saved somewhere in the workspace.</li> |
| </ol> Click <b>Next</b> to see the effect of applying the patch.</li> |
| <li> |
| <b>Optional Step</b>: <i>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.</i> In the Patch Target Specification page, you should |
| select the resource that is to act as the root of the patch. |
| </li> |
| <li>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. <b>Note:</b> The bottom pane <b>does not</b> show a preview |
| of how resources in your workspace would look after applying the hunk. |
| It just shows the contents of the patch file. |
| |
| |
| <ol type="a"> |
| <li> |
| 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. |
| </li> |
| |
| <li> |
| A red exclamation mark indicates that there is a problem with a patch or hunk. |
| <br> |
| 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. |
| <br> |
| You find the reason for the failure in parenthesis. |
| <p> |
| 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).</p> |
| </li> |
| |
| </ol> |
| </li> |
| <li>If all is well, click <b>Finish</b> to apply the patch. The workspace will |
| now contain outgoing changes for each file modified by the patch.</li> |
| </ol> |
| |
| |
| <H3>Options for applying a patch</H3> |
| |
| For getting successful matches of your patch file you have the following options: |
| <ol> |
| |
| <li> |
| Go back to the first page of the Resource Patcher wizard and |
| select the correct resource to which the patch should be applied. |
| </li> |
| |
| <li> |
| 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'. |
| </li> |
| |
| <li> |
| Use the 'Ignore whitespace' option to make the matching process |
| independent from whitespace differences between the patch file and files |
| in your workspace. |
| </li> |
| |
| <li> |
| 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. |
| </li> |
| |
| <li> |
| 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. |
| </li> |
| |
| <li> |
| 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. |
| </li> |
| |
| </ol> |
| |
| |
| <p><img border="0" src="../images/ngrelc.png" alt="Related concepts" ><br> |
| <a href="../concepts/concepts-26.htm">Team programming with CVS</a><br> |
| </p> |
| |
| <p><img border="0" src="../images/ngrelt.png" alt="Related tasks" ><br> |
| <a href="tasks-68.htm">Comparing resources</a> |
| </p> |
| |
| |
| <p><img border="0" src="../images/ngrelr.png" alt="Related reference" ><br> |
| <a href="../reference/ref-47.htm">CVS</a> |
| </p> |
| |
| |
| |
| </BODY> |
| </HTML> |
