Patch and Patch From

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 Change Packages .)

In this topic:

Structure of a Patch

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:

originally created in another workspace

created in the same workspace, then was promoted to the backing stream

Back to top

Patch vs. Merge

• 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:

  "combine my file with version v, taking into account only the recent changes to version v"

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

  a version that was originally created in another workspace

  ... or ...

  a version that was promoted to another stream

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.

Example 1

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.

Example 2

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.

Example 3

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.

Back to top

Invoking the Patch by Drag & Drop

If you have change packages enabled and use the classic GUI rather than the CLI, the most straightforward way to initiate patch operations (if needed) is to drag and drop issues in the StreamBrowser, from an Active Issues display to the destination stream or workspace.

AccuRev determines whether the changes can be automatically merged, and if not, invokes tools such as the Change Palette or a merge display to complete the necessary operations.

Following is a summary of the behaviors you will see in different scenarios.

Dragging to a Workspace

When you drag one or more issues to a workspace, AccuRev behavior depends upon the following considerations:

• If you drag a single issue to a workspace, AccuRev determines whether or not a manual intervention is required, and either offers to auto-merge, or brings up the merge display
• If you drag one or more issues to a workspace, and AccuRev determines that they do not require a patch, it automatically performs a Send to Workspace operation.
• If you drag one or more issues to a workspace and AccuRev determines that merging or patching is required, it displays the Change Palette in issue mode (see Work with the Issue Change Palette).

Dragging to a Dynamic Stream:

When you drag one or more issues to a dynamic stream, AccuRev behavior depends upon whether or not a patch is required:

• If a patch is required, AccuRev displays the Change Palette in issue mode
• If a patch is not required, AccuRev displays the Promote comment dialog box and prompts you through the promote process

Back to top

Invoking the Patch From Command

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.

AccuRev processes the files you specify one-by-one. For each file, it does one or both of the following:

• Prompts you, in one or more dialogs, to resolve namespace-level conflicts.
• Invokes AccuRev's Merge tool or the other tool you've configured, in order to perform the patch operation. AccuRev's Merge tool opens in a separate tab within the AccuRev GUI window; any other tool opens in its own window.

Notes:

• Patches involve real versions, not virtual versions

  AccuRev's patch facility involves working with the contents of text files. And AccuRev records changes to files' contents as real versions in workspaces. Accordingly, AccuRev only uses real versions in its patch manipulations. If you specify a virtual version in some dynamic stream as the "patch from" version, AccuRev automatically uses the real version for which the virtual version is an alias.

• What it means to be "between" the head and basis versions

  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:

  What if we patch from version wheat_dvt_john/42?

  

  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 this case, the difference between the two subsets of the element's version graph consists of eight versions, from two different workspaces.

Back to top

Patch Display

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.

Back to top

The Patch Algorithm

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

Back to top