\b0\fc1\cf1 FileMerge lets you easily compare two plain text (ASCII) or rich text (RTF) files. The files are displayed side-by-side, and their differences are highlighted. FileMerge also lets you merge the two files, creating a third file containing passages from either of the original files. FileMerge can also compare two directories, showing you which files have been added, removed, or changed.\
\b Note:
\b0 FileMerge is a new demonstration application in Release 3.2. It will eventually take its place in as a fully supported NEXTSTEP application, but for now consider it (and this documentation) preliminary and experimental. \
\fc0\cf0 \
\b\fs36\fc1\cf1 Specifying the Files or Directories to Compare\
\b0\fs24\fc0\cf0 \
To use FileMerge, you first specify two files or directories to be compared. This can be done in three different ways:\
\fi-360\li360
In FileMerge, choose the Compare Files command from the File menu. This displays a panel that lets you specify the two file to be compared. You specify the files by dragging them into the icon wells from the File Viewer, by typing their names in the text fields, or by clicking the Left and Right buttons above the icon wells and using the standard Open panel to navigate to each file. \
\fi0\li0 \
\fi-360\li360
In some application that lets you select directories (such as Workspace Manager), choose the Compare Files command from the Services menu. FileMerge will place the older of the two files in the left pane and the newer in the right.\
\fi0\li0 \
\fi-360\li360
From the command line, invoke FileMerge by issuing the the
\b opendiff
\b0 command (
\b /usr/bin/opendiff
\b0 ), specifying the two files to be compared:\
\fi0\li0 \
\pard\tx360\tx900\tx6120\fc0\cf0
\f3 opendiff
\i file1 file2
\f0\i0 \
\pard\tx360\tx6120\fc0\cf0 \
\i\fi-360\li360 file1
\i0 will appear in the left pane.\
\fi0\li0 \
Once you've specified the files to be compared, FileMerge opens a Comparison window and highlights the differences.\
\b\fs36 The File Comparison Window\
\b0\fs24 \
The Comparison window is divided into two panes; the top one displays the two files being compared, and the bottom one displays a file that would result from merging the top two files:\
Notice that the differences between the two files are highlighted in the top pane. Where a line has been added, the highlighting tapers from a fine gray line to a wider one that encloses the addition. Where a line has been removed, the highlighting tapers in the opposite direction. Each difference (known as a
\i diff
\i0 ) is also given a number, which is displayed in the central column. \
\pard\tx520\tx1060\tx1600\tx2120\tx2660\tx3200\tx3720\tx4260\tx4800\tx5320\fc0\cf0 As you move the cursor over the central column, the arrow changes to an open hand. Using the open hand cursor, you can drag the column to the left or right, revealing more of one or the other file. If you move the cursor over a diff, its image changes to a pointing hand. The pointing hand is used to select individual diffs, as described below.\
A few things to note:\
\fs10 \
\pard\tx360\tx6120\f1\fs28\fi-360\li360\fc0\cf0
\f0\fs24 To select text, you must hold down the Control key while dragging with the mouse. Note that when you do this the display of changes from gray highlighting to wire-frame. \
\pard\tx280\tx2520\tx2880\fc0\cf0 \
\pard\tx360\tx6120\f1\fs28\fi-360\li360\fc0\cf0
\f0\fs24 Using the Copy command when one or more diffs are selected will cause a textual representation of the selected diffs to be placed on the pasteboard. The representation used is the same as Unix's
You can select a diff by clicking it. A selected diff displays a black outline (as illustrated by diff 1 in the figure above). You can select the next or previous diff by using the arrow keys or by choosing the Next Difference or Previous Difference commands from the Find menu. To select multiple diffs, shift-click each one in turn.\
\b\fs36\fc1\cf1 \
Comparing Rich Text Files\
\b0\fs24\fc0\cf0 \
FileMerge can compare rich text files, but this feature should be considered especially experimental. When comparing rich text files the comparison is done on the textual contents of the file, not the formatting. Changing the font that some portion of the file won't be reflected as a change. Also, given that most paragraphs in a rich text file consist of single long lines (even though they're displayed as multiple lines due to wrapping), a single change in a paragraph will be displayed as a though the whole paragraph has been changed. This behavior is one of the things that might change in the future.\
Any feedback on usage of comparing rich text files would be appreciated.\
\b\fs36\fc1\cf1 \
Merging
\b0\fs24\fc0\cf0 \
The bottom pane of the Comparison window displays the file that would be the result of merging the two files under comparison. You will notice a splitview bar at the bottom of the window. Dragging the splitview will reveal a third file which is a "merged" file. When an ancestor file is not specified the merge file will initially be identical to the "right" (typically newer) file -- but more on ancestor files later. In either case you can review each diff and select whether the diff (or change) should be applied in the merge file.\
There are a number of ways to select which side of a diff to merge:\
\pard\tx360\tx6120\f1\fs28\fi-360\li360\fc0\cf0
\f0\fs24 Click the Choose Left or Choose Right buttons at the top of the merge pane.\
\f1\fs28
\f0\fs24 Use the Choose Left or Choose Right commands from the Edit menu. \
\f1\fs28
\f0\fs24 Use the left and right arrow keys (this works especially well when you use the up and down arrow keys to navigate to the previous or next diff). \
\f1\fs28
\f0\fs24 Double-click the text portion of the diff to indicate which file will contribute its version to the merged file.\
The merge file can be saved by choosing the Save Merge or Save Merge As commands from the File menu. \
\b\fs36\fc1\cf1 \
Ancestors
\b0\fs24\fc0\cf0 \
Frequently, one wants to simply view the differences between two files. For example, if one a copy of a file and has made changes to that file then it would be useful to review the changes before releasing the modified copy. In this situation, one might use the merge facility to simply omit some of the modifications that were made. The merge file would initially appear identical to the modified ("right") file and the user could iterate through each change, deciding whether to keep the change or not.\
Another less common but more difficult situation is one in which a file has been modified twice, independently. For example, you and a colleague both make copies of a file and each modifies the copy independently. This is often referred to as branching. In this situation you will want to specify an ancestor file. The ancestor file should be the file as it existed before it was modified. One of the modified files is specified as the "left" file and the other as the "right" file. So, "what does the ancestor file do?", you might ask.\
The ancestor file allows FileMerge to selectively take changes from the left file and the right file. For example: if 3 lines are removed from the right file (relative to the left) file, how can one tell whether they were specifically deleted from left or whether they were added to right. By verifying whether those lines existed in the ancestor file the system is able determine the answer to these types of question. \
When merging two files (and when an ancestor file is available) the system will "suggest" whether to choose "left" or choose "right" for each difference between left and right. Note that if some series of lines is changed in both the "left" and "right" files then FileMerge will not be able to determine which choice is correct. This situation is referred to as a conflict and will require that the user specifically choose.\
\b\fs36\fc1\cf1 \
Specifying Ancestor Files
\b0\fs24\fc0\cf0 \
The Compare Files menu item brings up a panel which allows you to specify the "left" and "right" files. Making this panel larger (in the vertical direction) will reveal two additional fields. One of these fields is the path name for the ancestor. If you're specifying directories, then the ancestor should also be a directory. If you're specifying files, then the ancestor should be a file.\
The second field is a "merge" path. Specifying the merge path is most useful when merging a number of files in a directory. FileMerge will compute the name of individual merged files relative to the path given here.\
\b\fs36\fc1\cf1 \
Saving Comparisons\
\b0\fs24\fc0\cf0 \
You can save a comparison to a file as a document. This might be useful, for example, if you want to send it to someone for review. To save a comparison, choose Save Comparison from the Comparison menu. When saving the comparison, you're given the choice of copying the contents of the files that were compared or saving links to those files. The latter choice is more space efficient, but you run the risk of those files changing from under you.\
Saving a comparison creates a file with a ".diff" extension. FileMerge claims those files.\
\b\fs36\fc1\cf1 \
Comparing Directories
\b0\fs24\fc0\cf0 \
When comparing two directories you get a window that contains a browser similar to the Workspace Manager file browser. The set of files in the browser is the union of those files found in the "left" directory and those files found in the "right" directory.\
Each file in the browser is in one of four states. If the file name is displayed in gray then the file from the "left" and the file from the "right" have identical contents. If the file name is displayed in black then the files are different. Additionally, when the file name is black, there may be a ">" or "<" symbol at the left of the file name. This indicates that the file was either added or deleted, respectively, from the "right" directory.\
You can double click a file name (or the Compare button) to bring up the file comparison window. You can also select multiple files and click the Compare button to get multiple file comparison windows. Clicking the Open button will open, in Workspace, both the left and right versions of the file.\
\b\fs36\fc1\cf1 \
Preferences\
\b0\fs24\fc0\cf0 \
FileMerge's Preferences panel lets you set these options:\
\pard\tx360\tx6120\f1\fs28\fi-360\li360\fc0\cf0
\f0\fs24 Compare rich text as ascii -- when enabled, comparing rich text files will be performed by stripping the rich text (in a temporary file) and doing the comparison.\
\f1\fs28
\f0\fs24 Number differences -- when enabled, each difference is numbered, starting from 1. This is convenient for remembering locations or describing locations to others (e.g. "look at difference 23...").\
\f1\fs28
\f0\fs24 Show merge direction -- when enabled, each difference is marked with an arrow, either pointing to the left or the right. The arrow indicates whether the change from the left file or the right file is selected in the merge file, respectively.\
\f1\fs28
\f0\fs24 Show change tick marks -- when enabled, each difference is shown as a tick mark in the scroller. This can be useful for finding all of the differences.\
\f1\fs28
\f0\fs24 Show \{ identical, added, deleted, modified \} files in browser -- for each type, one can enable or disable their display. For example, if you want to see only files which exist in both directories but have been modified, then select modified -- on and the rest off.\
\f1\fs28
\f0\fs24 Follow symbolic links -- when comparing directories it is sometimes useful to follow symbolic links. When enabled, directory comparisons will treat symbolic links as the file that they "reference".\
\f1\fs28
\f0\fs24 Files to ignore -- files which match any of the patterns listed will be ignored when comparing directories. For example *~ indicates to not consider files which end with the character ~.\
(.txt)