jMerge 0.9.1

Quick Start Guide

1. Loading Files Into jMerge - jMerge display differences between 2 files. To this, the files must be loaded into jMerge. Specify the paths to the files either by typing them or by using a chooser dialog.
   1. File Paths - There are 3 combo boxes in which to enter file paths: left, right, and center. The left and right combo boxes can contain either a path to a file or a directory. The center combo box can only contain a path to a file. The 3 combo boxes work together as described below.
      1. Two Files With Unique Paths - If you are comparing 2 files with completely different paths, then enter the full paths of each in the left and right combo boxes. The center combo box must be empty. For example, you want to compare

         /home/bob/src/com/project1/package1/HelloWorld.java

         and

         /home/doug/src/com/mystuff/package2/HelloWorld.java

         You would enter the following in the combo boxes.

         Left	Right
         /home/bob/src/com/project1/package1/HelloWorld.java	/home/doug/src/com/mystuff/package2/HelloWorld.java
         Center

      2. Two Files With Unique Roots But Common Subpaths - Often times, you are comparing files which have identical subpaths but unique roots. In these cases, enter the unique paths in the left and right combo boxes and enter the common subpath in the center combo box. For example, you want to compare

         /home/bob/development/src/com/project1/package1/HelloWorld.java

         and

         /home/bob/mainline/src/com/project1/package1/HelloWorld.java

         You would enter the following in the combo boxes.

         Left	Right
         /home/bob/development	/home/bob/mainline
         Center
         src/com/project1/package1/HelloWorld.java

      3. History - When you invoke the Refresh All operation, each of the combo boxes will retain the values of the paths entered.

   2. Choose File - Will bring up a standard file chooser dialog box. Once a file has been chosen, the path to that file will be entered into the corresponding combo box. NOTE: the file will not be loaded into jMerge until the Refresh All operation.

   3. Choose Directory - Will bring up a standard directory chooser dialog box. Once a file has been chosen, the path to that file will be entered into the corresponding combo box. NOTE: the file will not be loaded into jMerge until the Refresh All operation.

   4. Save - Saves any changes that were made to the file.

   5. Refresh All - Attempts to load both files into jMerge. The entries in the left, right, and center combo boxes will be used to locate both files. NOTE: you cannot load just one file. It will always load both. If there are any unsaved changes in either file, then you will be warned.

2. Selecting Lines Within A File - Each line within a file is selectable with the mouse.
   1. Single Line Selection - You can select a single line by a single mouse click on that line.

   2. Multi Line Selection - You can select a range of lines by doing a Single Line Selection on the first line followed by a Single Line Selection (plus the Shift key) on the last line.

   3. Double Click - You can peform a either Replace or Insert operation with a double click of the mouse on a line.

3. Operations On Selected Lines
   1. Delete - The selected line(s) will be removed from the file. If the permissions on the file are read-only, then this operation will be disabled.

   2. Edit / View - A dialog window containing a simple text editor will be displayed with the selected line(s) in it. The user can make whatever edits are necessary. Accepting the changes in the dialog window will replace the original selected line(s). This is true even if the original selected lines are no longer selected. Only one set of selected lines can be editted at a time.

   3. Clear - This unselects all lines in the file. If the permissions on the file are read-only, then this operation will be disabled.

   4. Replace - The selected line(s) in one file replace lines in the other. If the permissions on the file are read-only, then this operation will be disabled.
      1. If the destination file does not have any lines selected, the selected line(s) from the source file will replace the corresponding line(s) in the destination file.

      2. If the destination file does have one or more lines selected, the selected line(s) from the source file will replace the selected line(s) in the destination file. The number of selected lines on both sides does not have to match.

   5. Insert - The selected line(s) in one file are inserted in the other. The insertion point is before the first selected line. If the permissions on the file are read-only, then this operation will be disabled.

4. Color Codes For Line Differences

   Unselected Line	Selected Line	Meaning
   Black on white	White on black	Line is non-blank and identical to the line on the other side.
   Black on yellow	White on blue	Line is non-blank and different than the line on the other side.
   		Not a line at all -- just filler. The line on the other side does not exist on this side. Will not be Saved to the file.
   		Line is blank and identical to the line on the other side.

5. Status Bar
   1. Selected Line Range

   2. Total Line Count

   3. Lines Diff On Left

   4. Lines Diff On Both

   5. Lines Diff On Right

6. Advanced Features
   1. Pluggable Diff Engine - If someone wants to write their own differences engine, they can and still use this user interface.

7. Limitations - jMerge is still a work in progress. As such, there are definitely things that are missing or not fully implemented.
   1. No Undo Capability - My workaround for this is Save often. If a change really messes things up, use Refresh All.

   2. No Direct Support For Cut/Copy/Paste - My workaround for this is Edit/View. The Edit/View dialog windows do support cut/copy/paste.

   3. No Support For Drag & Drop

   4. No Support For Adding/Removing Other Diff Engines

8. Known Problems
   1. Simple Diff Engine - I know this diff engine is bad. It was meant as a basic implementation of the pluggable differences engine capability and not intended for use in production. I know there are other good diff algorithms out there.