Difference Section Color-Coding
Diff Toolbar Navigation Buttons
Editing a File Using the Diff Tool
The AccuRev GUI provides many ways to invoke a "Diff" command to compare two versions of a text-file element. By default, the comparison is performed by AccuRev's own Diff tool, which displays the two versions next to each other, using color coding to show the differences and provided convenient navigation controls. You can also configure the GUI to use another file-comparison tool.
No matter which tool you've configured to perform file comparisons, you invoke the tool in the same way, as described below. AccuRev's Diff tool opens in a separate tab within the AccuRev GUI window; any other tool opens in its own window.
There are multiple ways to specify the two versions of a file element to be compared:
In a File Browser, each file's context menu includes a Diff Against... item. There are several choices, each of which compares your version (i.e. the file in your workspace) with a version stored in the depot:
Most Recent Version: Compares your file with the version currently in your workspace stream. Use this choice if you've modified the file since the last time you performed a Keep on it (or if you've never performed a Keep on it since the last update).
Backed Version: Compares your file with the version currently in the backing stream. For example, you might use this choice to see all the changes you've made to this file since you updated your workspace and starting working on the file. (And assuming no one else has promoted a new version to the backing stream in the meantime.) This might include the changes stored in several intermediate versions that you've created with keep.
Basis Version: Compares your file with the version that you started working with, before making your "recent" changes. For a discussion of the meaning of "recent", see Patches and Change Packages.
File on Disk: Compares your file with an arbitrary file on your machine. A standard operating system "open file" dialog box open, in which you specify the file.
In a Stream Browser display, view the elements in a stream's default group The set of elements that are currently active in a particular workspace or stream. by clicking the control below the stream. An element's context menu includes the Diff Against... items described above.
In a Version Browser or Stream Version Browser display for a text-file element, you can compare any two versions: right-click any version, select Diff Against Other Version from the context menu, then left-click any other version.
In a History Browser display for a text-file element, you can compare the versions created in any two transactions. Right-click a transaction in the Summary (upper) pane, select Diff Against Other Version from the context menu, then left-click another transaction in the Summary pane. Similarly, the Diff Against File in the Workspace command enables you to compare the version created in a particular transaction with the file currently in your workspace. (That file might contain changes that you haven't yet preserved with Keep.)
The Diff tool displays the two versions side-by-side in separate panes, so that corresponding text lines in the versions line up visually. (You can use buttons Horizontal Layout and
Vertical Layout at the right side of the toolbar to arrange the panes above-and-below.) We'll call them the "before version" (displayed on the left, or above) and the "after version". The element pathname and the version-IDs are displayed above the versions' contents.
Initially, the two panes are the same width, but you can drag the vertical separator to change the relative widths. To make both panes wider, just increase the size of the overall AccuRev GUI window.
Notes (click to view):
The two versions being compared can have different pathnames: the element may have been renamed or moved to another directory within the depot. (This may have occurred in one of the versions, or in both of them.) The Diff tool does not highlight or announce such namespace differences A change to the pathname of a file or directory element: either renaming the element in place or moving the element to a different location in the depot’s directory hierarchy..
Depending on how you launch the Diff tool, an older version might be displayed on the right, and a newer version on the left. We recommend keeping the older version on the left, so that "before" and "after" in the descriptions below correspond to reality.
If the versions to be compared are in a binary image format that AccuRev can render, the Diff tool simply displays the versions, so that you can determine their differences by inspection. AccuRev can render the following image formats:
JPEG (.jpg or .JPG filename suffix)
PNG (.png or .PNG)
GIF (.gif or .GIF)
Applying changes from the "before" version to your workspace's version
If you're comparing the file in your workspace with another version, you can use the Diff tool to edit your file as you view the differences.
Through color-coding, the Diff tool partitions the text into the following kinds of "difference sections":
Unchanged Section (white background): Text section in which the versions are identical.
Added Section (green background): Text section that occurs only in the "after" version. Empty space with a blue background appears at that point in the "before" version.
Deleted Section (red background): Text section that occurs only in the "before" version. The deleted section appears with a blue background in the "before" version.
Changed Section (blue background): Sometimes, the Diff tool decides that a text section in the "before" version has been revised, producing the corresponding section in the "after" version. The before and after sections are not necessarily the same length, in which case some empty space is displayed in one of the versions. Both the before and after sections appear with a blue background. Both sections contain red character highlights, indicating the first location in a line where the two versions differ:
If a text block has been moved from one location in the file to another, the Diff tool indicates this as two separate changes: a deleted section at the original location, and an added section at the new location.
Your user preferences include controls for the Diff tool's handling of whitespace-only differences between the versions.
Most text files are too long to fit on the display screen, and some individual text lines are too wide. Accordingly, the panes in which the versions appear have both vertical and horizontal scroll bars. Scrolling of the panes is synchronized automatically. Line numbers appear at the left edge of each pane.
For a text file that contains hundreds or thousands of lines, there may be only a few difference sections (added, deleted, or revised), separated by large unchanged sections. The Diff tool provides both navigation buttons on its toolbar and a difference map for direct access to a particular difference section.
Whenever you use one of these buttons to jump to a particular difference section, the Diff tool remembers it as the current difference The currently highlighted difference section (Diff tool) or change section (Merge tool). and highlights the lines numbers in both panes. A "difference N of M" window in the toolbar indicates which difference section is current.
(Keyboard shortcut: Ctrl-F) Go to the first difference section.
(Keyboard shortcut: Ctrl-L) Go to the last difference section.
Using the scroll bars or the difference map, you can make the current difference The currently highlighted difference section (Diff tool) or change section (Merge tool). scroll offscreen. Click this button to bring it back onscreen.
(Keyboard shortcut: Ctrl-P) Go to the previous difference section.
(Keyboard shortcut: Ctrl-N) Go to the next difference section.
(Keyboard shortcut: Ctrl-S) Search for a text string, in either of the versions being compared. A dialog appears, in which you define the search.
This command is also available on the GUI window's main menu: File > Search.
After you've defined a search, you can perform it again, using the command File > Search Again on the GUI window's main menu, or its keyboard shortcut: function key F3.
Additional buttons on the toolbar support edit-by-diff operations.
To the right of each pane, there's a difference map that shows the relative locations and sizes of all the difference sections. The maps use the same color-coding as the difference sections themselves. Click on any colored area within a map to scroll both panes directly to the corresponding difference section. [note ]
Using a difference map merely scrolls the panes; it does not affect which difference is the current difference. After you jump to a particular location, click the difference section in either pane to make it the current difference.
If you use a difference map, but then want to scroll back to where you were before, click the Center Diff toolbar button.
In addition to comparing two versions of a file, the Diff tool can help you to edit the contents of the version in your workspace. This "edit-by-diff" capability is available only when you're comparing your workspace version with another version; it's not available when you invoke the Diff tool from the Version Browser or History Browser.
Here's a procedure for using this capability (there's a toolbar button summary below):
Invoke the Diff tool in a File Browser, to compare your workspace version with some other ("before") version of the same file.
Click the Show result of edits button in the Diff toolbar. This opens a third pane (the Edit pane), which initially contains the same text as your workspace version.
As you browse through the difference sections, you can:
Edit text manually in the Edit pane.
Click the Revert my change toolbar button to swap in the "before" version's text at that point (a change, addition, or deletion). The button becomes highlighted to indicate your selection.
Include both the "before" and "after" versions' text at that point: click the
Revert My Change toolbar button, then hold down the Ctrl key and click the
Restore my change toolbar button. Alternatively, click the two buttons in the opposite order. Both buttons become highlighted, and number annotations indicate the order you selected:
You can then modify the combined text manually.
Change your mind about a difference section where you've used and/or
, by selecting that section and clicking one of those buttons. Any manual edits you've made in that difference section are lost.
Click the Revert all of my changes button to make the Edit pane the same as the "before" version.
Click the Restore all of my changes button to make the Edit pane the same as the "after" version.
Finish your work in either of these ways:
Click the Save edits and close toolbar button. This simply replaces the file in your workspace. (It doesn't perform an AccuRev Keep command.)
Close the Diff tab to cancel the edit-by-diff session. No changes are saved to the file in your workspace.
Notes (click to view):
Using the edit-by-diff capability is similar to using the Merge tool. But there's an important difference:
An edit-by-diff operation involves just two versions.
A merge operation takes into account a third version: the closest common ancestor of the two versions being merged.
Revert my change
Use the "before" version's section at this point. If the button is currently highlighted, you can hold down the Ctrl key and press
to append the "before" section to the workspace version's section.
Restore my change
Use the workspace version's section at this point. If the button is currently highlighted, you can hold down the Ctrl key and press
to append the workspace version's section to the "before" section.
Revert all my changes
Make the Edit pane the same as the "before" version.
Restore all my changes
Make the Edit pane the same as the "after" version.
Save edits and close
Store the current contents of the Edit pane in the workspace's file, without performing a Keep The operation (keep command) that creates a new version of a file element in a workspace, permanently recording in the AccuRev repository a change to the contents of the file. operation.
Several of the commands in the Edit submenu of GUI window's main menu are enabled when you're working in a Diff tab:
Cut
(Keyboard shortcut: Ctrl-X) Cut the selected text to the window system's clipboard.
Copy
(Keyboard shortcut: Ctrl-C) Copy the selected text to the window system's clipboard.
Paste
(Keyboard shortcut: Ctrl-V) Paste the contents of the window system's clipboard.
Select All
(Keyboard shortcut: Ctrl-A) Select the entire contents of the current pane.
Search
(Keyboard shortcut: Ctrl-S) See the Search description above.
Search Again
(Keyboard shortcut: F3) See the Search description above.