Patch From (or Patch) perform a patch operation on a text-file element, incorporating some of the changes in a specified "patch from" version into the version in your workspace. The combined contents are saved, with Keep, as a new version in your workspace.
The patch operation is operationally similar to a merge operation, which incorporates all of the changes in a specified version. In fact, both operations use the same tool, either AccuRev's Merge tool or a third-party text-file-merge tool.
(An advanced extension of the patch concept called change packages, which integrates AccuRev’s SCM functionality with AccuWork’s issue management system is discussed in Chapter 10 Change Packages.)
Patch creates a new version in a workspace. This version is termed the head version of the patch. AccuRev automatically determines a corresponding basis version by scanning backward through the element’s ancestry. The basis version is the most recent version that was either:
Note: As of AccuRev 6.0, in certain circumstances users can specify the basis version, thanks to the introduction of multi-segments.
When you merge version v of a file into your workspace version, you are saying:
"combine my file with version v, taking into account all the changes in version v, back to the common ancestor"
When you patch version v of a file into your workspace version, you are saying:
To find the "recent changes to version v", AccuRev scans backward through the file’s ancestry, starting at version v and stopping when it encounters ...
This backward search defines a patch to the element. Version v is termed the head version of the patch. The older version is termed the basis version of the patch. The patch consists of all the versions of the element between the basis version and head version. The basis version itself is not included in the patch -- it precedes the set of "recent changes" in version v. The head version is included in the patch -- it contains the latest of the recent changes.
In identifying versions "between" the head and basis versions, AccuRev follows both direct ancestor and merge ancestry lines. In particular, if version v was created by a merge, its "recent changes" include both contributors to the merge.
Before Mary started her recent work, she updated her workspace. This brought in a version of the file originally created by another user -- say, version brown_dvt_john/5. Then she proceeded to create versions 5 through 7 in workspace brown_dvt_mary.
Derek decides to patch version brown_dvt_mary/7 into his workspace. He invokes the Patch From command from the context menu of this version. AccuRev searches backward through the element's ancestry, and includes the set of changes recently made in Mary's workspace: this set includes brown_dvt_mary/5 through brown_dvt_mary/7; the patch doesn't include the two versions created in workspace brown_dvt_john.
Mary started a task by bringing version brown_dvt_john/6 into her workspace with an update. Then she created versions brown_dvt_mary/4 through brown_dvt_mary/6, promoted her work to the backing stream, and then created two more versions: brown_dvt_mary/7 and brown_dvt_mary/8.
When John patches version brown_dvt_mary/8 into his workspace, AccuRev decides that only the versions since the promotion — versions 7 and 8 — contain "recent changes". The idea is that a promotion typically marks the end of a programming task, not an intermediate checkpoint.
Allison patches version trike_dvt_john/4 into her workspace, creating version trike_dvt_allison/1. Because John's version was created by a merge, the patch includes the recent changes to both merge contributors.
|
•
|
|
•
|
Note: If you attempt to patch into a workspace where a target element has unkept changes (has (modified) status), AccuRev alerts you and asks whether you wish to overwrite these unkept changes, or cancel the patch operation:
|
•
|
If a patch is not required, AccuRev displays the Promote comment dialog box and prompts you through the promote process
|
You can invoke Patch From on a selected version in the following contexts:
|
•
|
In the Version Browser (when invoked from a workspace), to patch from an arbitrary version.
|
|
•
|
In the History Browser (when invoked from a workspace), to patch from the version in a particular transaction.
|
In the simplest case, a patch's head version was derived from its basis version by a series of Keep operations (and maybe a Rename). In this case, it's easy to determine the set of versions that are between the head and basis versions. But what if one or more of the versions was created with Merge? Here's an example:
The basis version corresponding to this head version is the most recent one created in another workspace and brought into workspace wheat_dvt_john by an update -- that is, version wheat_dvt_mary/52. What versions are "between" these two versions? AccuRev determines the answer by finding this set difference:
In the Version Browser, a version created by Patch is connected to the "patch from" version with a dashed red line. Selecting this version highlights the versions in the patch.
The Patch From command performs its content-level work with the Merge tool. Submitting a different set of versions to this tool effectively implements the patch algorithm (see The Merge, Patch, and Reverse Patch Algorithms).