Back to DiffFork Page

Content

1   DiffFork

DiffFork is a diff tool for Mac OS X. DiffFork can compare both folders and files, presenting differences in a visual format.

2   Quick Start

  1. Create a new Diff window (Choose New Diff from the File menu).
  2. Drag and drop text files or folders on to the Diff window.
  3. Click the button on the right bottom of the window to start diff.

3   Diff Text Files

3.1   Block Guide and Scrolling in Sync

DiffFork supports Scrolling in Sync and Block Guide to help you identify the differences in the counterpart text files. Block Guide is the linking lines between the blocks.

3.2   Differences with Background Colors

Differences are marked with background colors according to their Types:

  • Red for removed
  • Yellow for modified
  • Green for added.

Differences in DiffFork have Levels to help you understand them more easily. For more information, please see the next section "Nested and Darker".

3.3   Nested and Darker

There are three level differences: Level 1(Block), Level 2(Line) and Level 3(Character). The Level 3 is nested in the Level 2, and the Level 2 is nested in the Level 1.

Nested differences are marked with darker background colors.

  • Level 1 (Block)

    Differences between lines. A Level 1 difference block can across multiple lines of text.

  • Level 2 (Line)

    Differences based on one line. The Level 2 difference always and only contains one complete line of text.

  • Level 3 (Character)

    Character (word) differences between one line.

These kinds of "Levels" may seem overly complicated, but it will feel more natural when you see how DiffFork presents differences in action. We hope these "colorful differences" can help you to understand the differences more easily.

3.4   Visual Feedback

When navigating the differences, the visual feedback mechanism proves very helpful.

3.4.1   Block (Level 1) Highlighting and Hint

A thin blue border will be displayed around the text of the selected block.

For the "insertion", a Ribbon (red or green, depending on the context) will be displayed to the left side of the text, in the place where the insertion is supposed to occur (or occurred).

(For more information about the ribbon, see the following section "Ribbons").

3.4.2   Line (Level 2) Highlighting and Hint

A small black dot will be displayed in the corresponding "Difference Ribbon", to the left of the selected line. The selected line will also look darker.

For the "insertion", a "Ribbon" (red or green, depending on the context) will be displayed to the left side of the text, in the place where the insertion is supposed to occur (or occurred).

3.4.3   Character (Level 3) Highlighting and Hint

For the "insertion", an icon (red or green, depending on the context) will be displayed below the line of text, in the place where the insertion is supposed to occur (or occurred).

3.4.4   Ribbons

DiffFork displays "difference ribbons" to the left of the text. Ribbons have the same background color as the corresponding differences, and they can be selected and highlighted as well.

3.4.5   Unmodified Blocks

Unmodified blocks (same text) can be selected, as well as other differences blocks, to help you find and locate the corresponding text. For more information, please see the next section "Aligning Blocks".

3.5   Aligning Blocks

To easily locate the differences in the counterpart text file, you can make DiffFork to align the blocks by selecting while pressing the Control key. You can change the preferences to use other modifier keys.

Suppose we are differencing text files A and B. When you align a difference (select a block or a line while pressing Control key) in A, the corresponding difference in the counterpart text file (B here) will be selected as well. In addition:

  • If the corresponding difference is not visible, the text editor is scrolled so you can see the difference.
  • The differences are aligned vertically when possible.

3.6   Edit in Place

You can "input wherever you have output". Differences will be updated according to your changes.

3.7   Encoding Detection

When you open text files, DiffFork attempts to determine the encoding of the files, so they can be read and displayed correctly.

See the Help for a complete encoding list.

3.8   The Fancy Insertion Cursor

The customized text editor supports customizing "Insertion Cursor". We love it, and we hope you will too.

3.9   Other things you may want to know

  • Line Wrapping. DiffFork can wrap long lines in the text editor. Choose "Wrap Lines" or "Wrap Lines (Both)" from the View menu.
  • Ignore Line break. DiffFork ignores line break differences (MAC/UNIX/DOS) when comparing text files.

4   Diff Folders

4.1   "Shadow diff" and "Binary diff"

The folder diff involves two steps: the first "Shadow diff" and the second "Binary diff". In the first step "shadow diff", DiffFork scans folders and do a fast inaccurate compare to find out the initial different items (files and folders). And then, in the second step "binary diff", items marked as SAME in the previous step are compared again byte for byte for accurate results.

4.2   Only items marked as DIFFERENT will be displayed

DiffFork displays differences only. Items with the same content will be hidden.

Differences include:

  • Files and folders only exist on one side.
  • Files with different content.
  • Folders contain different content.

4.3   How to read the results

There are two columns on the left of the item, which represent the diff results. The first column is for the left folder, and the second column is for the right folder.

The meaning of the icons:

  • Dot: File or folder exists.

  • Bold Dot: File has a newer modification date.

    Also, both compared files exist but the content is different.

  • None: File or folder doesn't exist.

4.4   Open a new text diff window

Double click the listed item to open a new text diff window.

4.5   Instant results display

When DiffFork scans folders and does the diffing, the results will be displayed as soon as possible when the underlying data is available. You don't have to wait until the whole process is completed.

4.6   Exclude rules

DiffFork uses a config file to control its behavior when it scans for files that it is to exclude. Excluded files will not be diffed and displayed.

To edit the config file, choose Preferences... from the application menu, and switch to "Folder Diff".

4.6.1   Syntax

The config file consists of a list of patterns, with one pattern a line. The # character is treated as a comment character.

Two types of pattern syntax can be used: glob and regular expression. To change the syntax, use a line of the following form:

syntax: TYPE

TYPE is one of the following:

  1. glob: Shell-style glob, the "*" character matches any string.
  2. regexp: Regular expression, see the Help for a short reference.

The assigned syntax stays in effect until another type is specified. You can also assign a syntax for a pattern using prefix, which overrides the global syntax. An Example:

regexp: (^|/).

4.6.2   The Performance Effect

Applying exclude rules on each file takes time, which may slow down the diff process dramatically. Set up the rules with care to avoid the performance issue.

5   Others

5.1   Version Control System integration

Starting from version 1.1.6, the DiffFork command-line utility supports OPTION "-w --wait", which can be used to help work with Git, Mercurial, Subversion, etc.

Note: DiffFork can compare 2 folders/files. 3-way diff/merge is not supported.

To install the command-line utility, choose "Install Command-Line Utility..." from the Help menu.

    USAGE
      difffork file1 file2 [OPTION]
    DESCRIPTION
      -w --wait
         Wait for the diff window to be closed.
  

The integration instructions provided in this document is a starting point. For more information, please reference the VCS document or contact us for support.

Git

  • Create a shell script gitdfdiff.sh with the following content:
  •       #!/bin/sh
          difffork "$2" "$5" -w
        
  • set the GIT_EXTERNAL_DIFF variable in shell, replace FULLPATH with your full script path.
  •       export GIT_EXTERNAL_DIFF=FULLPATH
        
  • In your Git working directory, type:
  •       git diff
        

Mercurial

Mercurial has a detail instruction on how to use external programs to compare revisions, or revision with working dir: http://mercurial.selenic.com/wiki/ExtdiffExtension

To use extdiff command:

  • Enable the extension (in ~/.hgrc):
  •       [extensions]
          hgext.extdiff =
        
  • Use the -p option specify DiffFork as external diff utility, and -o option to specify options.
  •       hg extdiff -p difffork -o -w
        

To create custom extdiff commands:

  • Add new command
  •       [extdiff] 
            # add new command that runs DiffFork
            cmd.dfdiff = difffork
            opts.dfdiff = -w
        
  • Invoke the new command
  •       hg dfdiff
        

Subversion

Subversion has an instruction on how to use external programs: http://svnbook.red-bean.com/en/1.5/svn.advanced.externaldifftools.html

  • Create a Python shell script svndfdiff.py with the following content (replace FULLPATH with your full difffork path):
  •      #!/usr/bin/env python
         import sys
         import os
    
         # Configure your favorite diff program here.
         DIFF = "FULLPATH"
    
         # Subversion provides the paths we need as the last two parameters.
         LEFT  = sys.argv[-2]
         RIGHT = sys.argv[-1]
    
         # Call the diff command (change the following line to make sense for
         # your diff program).
         cmd = [DIFF, LEFT, RIGHT, '-w']
         os.execv(cmd[0], cmd)
    
         # Return an errorcode of 0 if no differences were detected, 1 if some were.
         # Any other errorcode will be treated as fatal.
    
      
  • In your Subversion working directory, type:
  •      svn diff --diff-cmd svndfdiff.py