Diff mode help.

Name:	Diff Mode
Version:	6.0
Last update:	2020-08-28 10:40:57

Introduction

The Diff mode for Alpha is used by the Diff Windows produced when Alpha executes a comparison between two objects (document windows, or selections, or files, or folders). The comparison functions are provided by the Tools ↣ Compare submenu (see the Compare Help page).
The Diff mode implements the navigation between differences in the Diff Windows, and provides commands to patch differences back and forth between the two files.
It also installs a menu called Diff in the menu bar when the active window is in this mode. See the Diff Menu Items section for more information.

Diff Windows Navigation

After the execution of a comparison command from the Tools ↣ Compare submenu, Alpha displays the results in windows called Diff Windows. These windows contain the information about the differences found between the two objects. There are two kinds of Diff Windows: one for file comparisons and one for folder comparisons. The windows are in Diff mode.
You trigger different actions using key combinations, as explained in th next paragraphs). The Diff Window must be the active (frontmost) window for the key combos to work.

File comparison

In order to select a particular difference, you use the Up and Down arrow keys to move around and then you press the Return key to visualize the corresponding sections in the document windows.
Use the Control-Option-Left and Control-Option-Right key combos (⌃⌥-Left and ⌃⌥-Right) to patch changes from one window to the other.

Folder comparison

The Diff Window in that case gives a list of the files which differ between the two folders. You use the Up and Down arrow keys to move around the lines and, once you have selected a line that indicates that two files differ, you press the Return key to execute the actual comparison: this opens a new Diff Window with the results of the file comparison.
You can also use the Control-Option-Down and Control-Option-Up key combos (⌃⌥-Down and ⌃⌥-Up) to select the next line reporting a difference and execute the comparison.

External comparisons

You may also edit, with Alpha, files that contain the results of a comparison executed with an external tool (such as the diff command line). If these files have a .diff extension, Alpha automatically opens them in Diff mode and does its best to provide the same functionalities as with internal comparisons, but sometimes it needs some help from the user to identify and locate the original files (or folders) that were compared. The diff files do not always contain this information. This is the role of the following menu items found in the Diff menu: Locate Left Window…, Locate Right Window…, Locate Left Folder… and Locate Right Folder…. These menu items are enabled only if you are editing an external diff file.
If the diff file corresponds to a folders comparison, Alpha tries to establish if the parent folder of the diff file could be the basis for the relative paths found therein. If this is the case, Alpha will base its navigation on this parent folder. But this heuristics is fragile because it could just be wrong and also because the compared files may have changed since the diff was executed. It is the responsability of the user to ascertain what the compared files or folders are and to provide them if necessary using the above-mentioned menu items.
In conclusion, open any .diff file, locate either the left or right file or folder with the commands above, and then you can patch in changes from the diff window using ⌃-Left or ⌃-Right as appropriate.

Diff Menu Items

Here is the signification of the various menu items found in the Diff menu.

Rerun Diff: Re-execute the comparison corresponding to the active Diff Window.
Refine Diff: Refine the comparison corresponding to the active Diff Window. When diffing files in a mark-up language like TeX or HTML, where line breaks are not themselves significant, it often happens that a big block of text is flagged as changed, although in reality the paragraph has just been reflowed. In this situation, you can use this command (which can also be invoked just by pressing 'r' while the Diff window is frontmost). This will spawn a separate word-by-word diff on the two selections, which will pinpoint what actually changed inside the paragraph. During this subordinate diff run, you can patch as usual, and when you have finished, just close the auxiliary diff window to return to the overall diff job.
Patch Into Left Window: Apply a difference from the right document to the left one. This command is ignored by folder comparisons.
Patch Into Right Window: Apply a difference from the left document to the right one. This command is ignored by folder comparisons.
Locate Left Window…: When you are editing an external diff file, use this command to help Alpha find the left window that led to this file.
Locate Right Window…: When you are editing an external diff file, use this command to help Alpha find the right window that led to this file.
Locate Left Folder…: When you are editing an external diff file, use this command to help Alpha find the left folder that led to this file.
Locate Right Folder…: When you are editing an external diff file, use this command to help Alpha find the right folder that led to this file.
Parse Diff Window: When you are editing an external diff file, this forces Alpha to (re-)parse the contents of the file in order to find the diff codes and (re-)build its internal registers.
Diff Prefs…: Display the Diff mode preferences.
Diff Help: Display this help file.

Examples

Some example files are available: see the Examples section of the Compare Help page.

Diff Mode Preferences

Inspect the Diff Mode Preferences for various options that can be set to control the behavior of diff operations.
Here is the meaning of these preferences:

Diff Window Added Color: The Diff window color indicating text that has been added.
Diff Window Changed Color: The Diff window color indicating text that has changed.
Diff Window Removed Color: The Diff window color indicating text that has been removed.
Display Only Diff Codes: If this option is set, don't display the differing lines (just the diff codes) when comparing two files.
Font Size While Diffing: Font size used temporarily for windows being diffed.
Kill Windows When Done: Automatically close document windows after the diff is complete if they were not open when the diff began.
Remove File Prefix: If you've imported a diff file from a different folder structure, you can remove this prefix so Alpha finds your files correctly.
Show Info Opening External Diff: When an external diff file is opened, Alpha displays an informative dialog reminding how to locate the left and right windows or folders corresponding to this diff file. Turn this option off to bypass the dialog.
Translate Path Delimiters: Automatically translate the path delimiters in external diff files generated by different platforms (i.e. Unix, Windows, MacClassic)

Technical issues and limitations

The main feature which is lacking is an 'unpatch' feature. You will have to make do with Alpha's 'Undo' facility for the moment. (Basically the problem is if you patch section 'a', then patch section 'b', you can't undo 'a' without undoing 'b' first).
Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 1997-2020, Vince Darley and Contributors.
Contributors: Joachim Kock, Jon Guyer, Craig Barton Upright, Bernard Desgraupes.
All rights reserved.
The Diff Mode package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Vince Darley nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VINCE DARLEY OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.