How to Use Xcode's FileMerge Tool to Compare Files


An often overlooked app, Xcode FileMerge allows you to determine what changed between two files. Here's how to spot differences using this tool.

Most Apple software developers are familiar with the Apple Xcode integrated development environment (IDE).

But Xcode has several utility apps that are often overlooked.

This is:

  1. Accessibility Inspector
  2. ML Creation
  3. FileMerge
  4. Tools
  5. Reality Composer Pro

Some of these applications, such as Reality Composer Pro and Create ML, are new, but one utility, FileMerge, has been around for decades and is part of OpenStep – the original developer tools created by Steve Jobs' other company, NeXT, in the early 1990s .

Apple bought NeXT in 1997, and its software and operating system (NeXTStep) became what is today macOS, iOS and Xcode.

Applications in the Applications folder of Xcode.

In fact, FileMerge Xcode is one of the few applications left today from the original NeXTStep that has remained virtually unchanged.

FileMerge was originally created as a tool for developers to compare and merge source files, but it works great with most plain text files (.txt).

FileMerge source application in NeXTStep.

Accessing FileMerge

FileMerge is located inside the Xcode application package in the Applications subfolder of the Contents folder. So the path to FileMerge in the Xcode package is:

There are two ways to access FileMerge: you can launch it from within Xcode by selecting the menu Xcode->Open Developer Tool->FileMerge in Xcode, or you can open the Xcode app package itself in Finder, open the /Contents/Applications subfolder, then drag FileMerge into the Dock to create a shortcut for it.

To open an Xcode package, Ctrlclick the Xcode icon in the Finder while holding down the Command key on your Mac keyboard and selecting Show Package Contents

strong> in the pop-up menu that appears:

Open an Xcode app package in the Finder.

The terms “package” and “package” are synonymous in macOS. Packages are simply folders that have special bits set that tell Finder that they contain executable code.

You can also Command-OptionDrag the FileMerge app from the Xcode Applications folder to the Finder desktop by holding down these keys on your Mac keyboard and clicking the app icon in the Xcode Apps folder. and drag it to the desktop. This will create an alias for the FileMerge shortcut on your desktop.

Open FileMerge from the Open Developer Tool menu in Xcode.

You can Command-click yourself Xcode icon if it's in the Dock in Finder, and select the Open Developer Tool->FileMerge menu item from the pop-up menu to open FileMerge. This has the same effect as opening it directly from Xcode.

Either of these methods will work to open FileMerge – just don't remove the application itself from the Xcode package, otherwise this may damage the integrity of the Xcode application.

Open FileMerge from the Dock.

Using FileMerge

Once FileMerge is open, its interface is very simple: you are presented with one small window with two levels: one for the original file you want to compare (“Left”), and one for the newer file (“Right”), which should be like this the same, but contain some changes compared to the original. Both files must be regular text files to compare differences, but you may find that FileMerge works with some other limited text file types as well.

FileMerge cannot handle most encoded text files, so it's best to use it with plain text. If you try to compare encoded files using FileMerge, you'll likely get a “Files are not ASCII” warning and ask if you want to continue anyway.

If you choose to continue, the files will be compared, but you will only see encoded comparisons, which are usually meaningless: FileMerge doesn't know how to decode most files.

ASCII is an acronym for American Standard Code for Information Interchange, an ancient 8-bit encoding of Latin text. ASCII has since been replaced by Unicode, which is a 16-bit text encoding, because it supports multi-byte characters in other languages, such as Asian and Arabic languages, which have larger character sets and special characters.

Although Unicode is now the worldwide standard for text encoding on computers, some older 8-bit ACSII files may still be encountered in everyday use.

Here is the FileMerge user interface:

FileMerge main window.

You can press Left and the buttons Right using the standard macOS Open sheet, or you can drag two files from the Finder into the left and right image panes on the right side of the FileMerge window. Doing any of these actions has the same effect.

Once both files are installed in FileMerge, you will see their file paths on disk appear in two edit boxes next to the Left and Right buttons.

Now you are ready to compare files. To demonstrate, we will use a trivial example.

File comparison

Once your files are set in the FileMerge interface, click Compare button in the lower right corner of the main window. This will start the FileMerge comparison and open a new diff window with both files, highlighting the changes in each.

In the differences window, the original file is shown on the left, and the modified (new) file is shown on the right. Changes are indicated by colored bars that vary depending on the portions of text changes in the modified file.

FileMerge differences window.

As you scroll through the text of a file, FileMerge displays these wonderfully ingenious bars to animate which sections of the text have changed. Large sections scroll more slowly, so the opposite file may catch up.

If a block of text is pasted into a newer file, the entire block is highlighted, but its insertion point appears in another file of the same color, with a thin stripe extending from the side containing the pasted text. As you scroll through the differences window, the bars move smoothly so you can see what has changed.

For single-line changes or changes of just a few lines, the diff window highlights the changed lines with similar bars, but only a few lines high.

In the center of the diff window is a single column with arrows indicating which of the two files contains the changes. Arrows can go in both directions: left and right. You can select any individual text change by clicking the change bar in the center column where each change arrow is located.

To select a change you need to click in the center column – clicking on the change bar in the left or right pane of the diff window does nothing. Above each change arrow is a number indicating the change number at the top of the file.

If the files being compared are source code files in any standard programming language, the comparison window also displays a pop-up menu at the top of the left and right comparison panes. Each menu contains all the function or method names in the files, and selecting a method name from any menu allows you to jump to that method in the file.

Using Ancestor and Merge

At the bottom of the FileMerge window, you will notice a small note: “Enlarge the window to indicate ancestor paths and/or merge paths.”

If you click and drag the bottom of the FileMerge window down, you will see an additional interface:

Using the Ancestor/Merge panel.

This user interface allows you to add an optional third file for a three-way merge. To hide the Ancestor/Merge user interface, simply click and drag it back up at the bottom of the FileMerge window.

Merging Changes

Once the Differences window opens and FileMerge shows the differences between them with change bars, you can choose how you want to process every change: you can either ignore every change, copy the new text to the opposite file (merge), or delete the specific change.

These actions are performed using the Actions pop-up menu in the lower right corner of the comparison window.

The following options are available in the menu:

  1. Select left
  2. Select right
  3. Select both (left first)
  4. Select both (right first)
  5. Select neither

If you choose either of the first two options, changes will be made to the file on the left or right. Selecting any of these options determines which file receives the change.

If you select either of the Select both options, the change will be added to both files depending on what changed in the left or right file.

If you select Select Nothing, the arrow for that change will disappear from the center column, indicating that the change will be ignored.

No matter what action you select from the pop-up menu, the change is made and the arrow in the center column of the differences window is updated to reflect the new reality.

Also, note that there is no Edit button in the user interface: when you select an action from the pop-up menu, the change is made instantly, without any additional warning or interaction with the user. .

Saving changes to disk

After making all changes in the differences window using the menu ActionYou will still have to save the changes to disk for them to persist.

Unlike regular text editors, FileMerge does not automatically save changes to source files when you select File->Save Merge from the File menu. menu. This is so that your source files can be kept intact in case you want to use them later as is.

Instead, when you select File->Save Merge, you will always be presented with the standard Save panel so you can decide what to do – if you click Savein the same location as the original left file. If you want to replace the original, you will get a promotion. If you click Replace, the original file will be overwritten.

Or, if you want to save the original file with the same name in a different location, you can navigate to it and click the Save button or rename the file. file to something else and save it in the same location as the original. This will create a new file with the name you choose.

File->Save Merge Asis essentially the same as Save, but you need to give the file a new name so that a new file is created.

After making changes using the Actions menu in the diff window, you will be prompted to save the merge if you try to close the window or exit FileMerge. If you try to close the diff window without saving, you will be prompted with a warning asking if you want to save.

You can Cancel from the alert or click Don't Save to discard the changes.

If you click the Save buttonin the alert, it will be the same as if you had selected File->Save Merge from the File Menu.

In any case, after saving the merge, the resulting file now contains all the changes you made to the diff window. Unless you explicitly overwrote the original file, it will remain untouched.

Directory comparison

You can also compare two folders (directories) containing files using FileMerge. To do this, use the methods above, but select two folders in the Left/Right interface instead of two files.

The main functionality of comparing folders in FileMerge is to check sets of files for identity, modify files in any folder, or add or remove files from any folder.

When you click the Compare button on two file folders, FileMerge scans both sets, comparing all the files contained in both folders.

The resulting folder comparison window shows the differences between the sets of files in each folder:

Directory comparison results window.

If both folders contain two files with the same name, these file names will be shown in gray on the left. If a file is present in one folder but not in another, its name is italicized.

When you single-click any file name in the left panel, the status of that file is displayed in the lower left corner of the panel.

You can specify which folder change options you want to exclude in the right pane called Exclude.

Below there are two pop-up menus: the first contains elements for viewing and comparing files. Selecting an item from this menu performs similar actions to the Actions menu in the comparison window.

Another pop-up menu called Mergecontains options for moving or merging files between the two folders being compared. You can merge files, choose to use only the left or right file, delete files entirely, and remove from the list any files that cannot be compared.

The View and Merge controls can be confusing and violate Apple's user interface guidelines because, unless clicked, they display what should be menu labels: when you click on either them, the headings “View” or “Merge” appear. will disappear from any menu and then reappear when you release the mouse button.

Use the Merge menu with caution.

After using the Mergemenu, the small status message in the lower left corner of the window updates to reflect the changes. Keep in mind that this window is primarily for merging or moving files between the two folders being compared.

Find, Re-Compare, and Reset in FileMerge

After running a file comparison in FileMerge, you can view any differences in the Differences window as above by scrolling through them, or use the Find menu in the row FileMerge menu. at the top of the screen.

Search options in FileMerge:

  1. Go to next
  2. Go to previous
  3. Go to line/diff
  4. Find
  5. Find next
  6. Find previous
  7. Use selection to search
  8. Go to selection

The Next/Previous options allow you to move to the next or previous diff, changes to the left or right side of the diff window, or to the next conflict. Conflicts are two nearly identical blocks of text, each containing changes that make exact comparisons impossible.

You will have to resolve conflicts manually.

If you highlight any text in the comparison window and then select Find->Use Selection to SearchFileMerge will open the search window, but will automatically insert the selected text into the search window. Find your search field.

Once the comparison is complete, you can reset FileMerge to its original state by closing the comparison window and selecting File->Compare Files. This will reopen the main FileMerge window, but your last selected file paths will remain untouched.

You can also select File->Compare Files Again to perform the previous comparison again. This is useful if you make external changes to files, save them, and then want to compare them again after making the changes.

FileMerge Settings

If you select FileMerge->Settings in FileMerge In In the menu bar at the top of your Mac screen, you'll see a FileMerge preferences window that allows you to set different FileMerge behavior options:

  1. Wrap text
  2. Show change numbers
  3. Show merge direction
  4. Show changes in scroll bar
  5. Highlight differences
  6. Font
  7. Directory comparison options
  8. Filters to compare
  9. Files to ignore

To save changes to FileMerge settings, simply make your changes and close the window.

FileMerge Preferences Window.

FileMerge has been a mainstay of macOS Developer Tools for decades, but it's so useful that you'll probably want to use it. daily once you understand how it works. Its interface takes us back to an era when software was small, simple, fast and easy to use.

This is a hidden gem that's been lurking in macOS for a long time—and once you discover its easy file comparison ability, you'll wonder how you ever got by without it.

Leave a Reply