NAME¶
mgdiff - Motif-based graphical file difference browser
SYNOPSIS¶
mgdiff [-toolkitoption ...] [-quit] [-file
name] [-args
diffargs]
[file1 file2]
DESCRIPTION¶
Mgdiff is a graphical front end to the
diff command. It permits
the user to view the differences between two ASCII files in context and,
optionally, to write out a third file which is the user-defined merging of
those two files. It is inspired by a similar program, called
gdiff,
which runs only on Silicon Graphics workstations and for which source code is
not provided.
The program takes as arguments various flags (described in the next section) and
the names of two files to compare. Either filename (but not both) may be given
as '-' to use standard input instead.
The resulting display consists mostly of two panes of text; the one on the left
is the first file specified and the one on the right is the second file
specified. Between and below the text panes are scrollbars that permit
changing the visible portions of the two files being compared. In addition,
the program implements the Scrolled Region recommendations of Section 2.3.4 of
the OSF/Motif Style Guide (release 1.1), meaning that the arrow and paging
keys will work to scroll as well. Above each text pane is the name of the file
in that text pane and the line number in the file which is being displayed.
The text in each of the text panes is divided into blocks of lines which are
color-coded with one of five different colors. This indicates that the block:
- differs between the two files
- is identical between the two files
- has been inserted in one file or the other
- is for display purposes (to match an inserted block in the other
file)
- has been selected by the user (for writing to a merged file)
These colors can be modified by the user via X resources; see the RESOURCES
section of this manual page. A legend display of the colors and their meanings
is available using the Help menu.
On the right-hand side of the display is an overview area; this shows the files
in their entirety. The sliders in the overview area track the lines being
displayed in the text panes.
At the top of the display is a Motif menu bar; those functions are discussed in
the MENUS section of this manual page.
Earlier versions of this program (pre 2003) only allowed the selection of the
left hand side difference or the right hand side difference. It also would not
allow a file to be saved with unselected blocks. The current version allows
the user to select both sides of a difference by selecting blocks using the
middle mouse button. When both sides of a difference are selected both blocks
will be saved to the merged file and marked in a similar manner to the way
CVS marks merges that require manual resolution of conflicting changes.
In addition, the current version also allows saving of a merged file with
unselected blocks. In this case, the merged file will contain neither the left
hand side nor the right hand side of the unselected blocks.
COMMAND LINE OPTIONS¶
- -toolkitoption
- These are the standard options accepted by all applications that use the X
Toolkit Intrinsics. See the OPTIONS section in the X(1) manual
page.
- -quit
- This option sets the resource Mgdiff.quitIfSame to
"true". This will cause the program to exit immediately without
bringing up a window if the two files have no differences (as determined
by the diff command).
- -args diffargs
- This option sets the resource Mgdiff.diffArgs to the value of the
diffargs argument. These flags are passed to the diff
command that actually computes the differences between the two files.
Since any argument can be passed, it is possible to specify flags that
cause the diff command to fail or to generate output in a different
format that will cause mgdiff to fail. For most versions of
diff, only three flags make any sense. The first is '-b'; this
causes diff to ignore trailing blanks (spaces and tabs) and to
treat all other strings of blanks as equivalent. The second flag is '-w';
this ignores blanks and treats strings of blanks as equivalent. The last
flag is '-i'; this ignores case when comparing letters.
- -file name
- This command sets the resource Mgdiff.filename to the value of the
name argument. mgdiff uses this string to display over a
file read from standard input.
The menubar contains the following menu topics as CascadeButtons:
File,
View,
Select,
Options and
Help. The rest of this
section discusses each menu entry, showing it's name and accelerator, if any.
- File
This pulldown menu controls file access:
- Open...
- Ctrl+O
Brings up the "Open Files" FileSelectionDialog to allow the user to
open two files for comparison.
- Open Left...
- Ctrl+L
Brings up the "Open File" FileSelectionDialog to allow the user to
specify a file to open and compare with the already opened right-hand file.
- Open Right...
- Ctrl+R
Brings up the "Open File" FileSelectionDialog to allow the user to
specify a file to open and compare with the already opened left-hand file.
- Save As...
- Ctrl+S
Brings up the "Save File" FileSelectionDialog to allow the user to
specify an output file for writing the merged file; this is an application
modal dialog. The program will allow the user to overwrite an existing file
but pops up a QuestionDialog to allow the user to cancel the operation if
desired. If there are any unselected areas of difference between the two files
the user is asked whether they want to continue or cancel the operation. If
the user continues, the output file will contain none of the unselected
blocks.
- Save As Left...
Saves the merged file to the location given by the left hand side file location.
The user will be asked if they are sure they wish the existing file to be
overwritten. As with the "Save As", if there are any unselected
areas of difference between the two files the user asked whether they want to
continue or cancel the operation. If the user continues, the output file will
contain none of the data in the unselected blocks.
- Save As Right...
Saves the merged file to the location given by the right hand side file
location. The user will be asked if they are sure they wish the existing file
to be overwritten. As with the "Save As", if there are any
unselected areas of difference between the two files the user asked whether
they want to continue or cancel the operation. If the user continues, the
output file will contain none of the data in the unselected blocks.
- Exit
- Ctrl+C
Exits the program immediately.
- View
This pulldown menu contains commands for moving through the files.
- Previous
- Ctrl+P
Scrolls both file views so that the previous area of difference is
Mgdiff.linesOfContext lines from the top of the application window.
- Next
- Ctrl+N
Scrolls both file views so that the next area of difference is
Mgdiff.linesOfContext lines from the top of the application window.
- Next Unselected
- Ctrl+U
Scrolls both file views so that the next unselected area of difference is
Mgdiff.linesOfContext lines from the top of the application
window.
- Select
The two files being compared can be optionally merged into one file. To do this,
the user must select for each area of difference between the two files which
version should be written to the merged file. The menu entries in this
pulldown menu allow the user to select or unselect differences in groups
rather than individually.
- Left All
For all areas of difference between the two files select the left-hand file
version.
- Right All
For all areas of difference between the two files select the right-hand file
version.
- Unselect All
Unselects all areas of difference in both files.
- Options
This pulldown menu controls miscellaneous appearance and/or behavior options.
- Overview
- Ctrl+W
This menu entry toggles the presence of the overview area on the right-hand side
of the application window. The default value for this toggle is controlled by
a resource,
Mgdiff.overview, which is described in the RESOURCES
section.
- Horizontal Scrollbar
- Ctrl+H
This menu entry toggles the presence of the horizontal scrollbar at the bottom
of the application window. The default value for this toggle is controlled by
a resource,
Mgdiff.horzScrollbar, which is described in the RESOURCES
section.
- Drag Scroll
- Ctrl+D
This menu entry toggles the behaviour of the scrollbars in the application
window. When set, dragging the slider of a scrollbar results in a immediate
change in the view of the text being compared. When unset, the view is only
changed at the end of a slider drag (when the mouse button is released.) This
setting might be preferred on a slower X server. The default value for this
toggle is controlled by a resource,
Mgdiff.dragScroll, which is
described in the RESOURCES section.
- Help
This pulldown menu displays commands for obtaining help on or information about
mgdiff.
- Version...
- Ctrl+V
Brings up an InformationDialog with author and version information.
- Manual Page...
- Ctrl+M
Brings up a DialogShell with a ScrolledText widget containing this manual page.
The command for generating this is customizable via a resource,
Mgdiff.manCommand, which is described in the RESOURCES section.
- Color Legend...
- Ctrl+G
Brings up a DialogShell which summarizes the use of color in encoding the types
of differences between the two files being compared.
OTHER DISPLAYS/CONTROLS¶
You can move directly to a particular spot in the two files by using
BDrag in the overview area.
The program uses what the OSF/Motif Style Guide calls "multiple
selection" to select individual blocks for writing to a merged file.
Clicking
BSelect on an unselected block adds it to the list of selected
blocks. Clicking
BSelect on a selected block removes it from the list
of selected blocks. In addition, Clicking
BSelect on an unselected
block which is opposite a selected block (in the other text panes) removes the
selected block from the list of selected blocks.
The numbers in the small boxes next to the file names are the line numbers of
the lines at the top of the text panes.
What follows is the hierarchy of Motif widgets, as generated by
editres(1). The hierarchical structure of the widget tree is reflected
in the indentation. Each line consists of the widget class name followed by
the widget instance name. This information might be useful if you wish to
customize the appearance of the program via resource settings.
Mgdiff mgdiff
XmMainWindow mainw
XmSeparatorGadget MainWinSep1
XmSeparatorGadget MainWinSep2
XmSeparatorGadget MainWinSep3
XmRowColumn menubar
XmCascadeButtonGadget button_0
XmCascadeButtonGadget button_1
XmCascadeButtonGadget button_2
XmCascadeButtonGadget button_3
XmCascadeButtonGadget button_4
XmMenuShell popup_file_menu
XmRowColumn select_menu
XmPushButtonGadget button_0
XmPushButtonGadget button_1
XmSeparatorGadget separator_0
XmPushButtonGadget button_2
XmRowColumn file_menu
XmPushButtonGadget button_0
XmPushButtonGadget button_1
XmPushButtonGadget button_2
XmPushButtonGadget button_3
XmSeparatorGadget separator_0
XmPushButtonGadget button_4
XmPushButtonGadget button_5
XmSeparatorGadget separator_1
XmPushButtonGadget button_6
XmRowColumn options_menu
XmToggleButtonGadget button_0
XmToggleButtonGadget button_1
XmToggleButtonGadget button_2
XmRowColumn help_menu
XmPushButtonGadget button_0
XmPushButtonGadget button_1
XmPushButtonGadget button_2
XmRowColumn view_menu
XmPushButtonGadget button_0
XmPushButtonGadget button_1
XmPushButtonGadget button_2
XmForm form1
XmFrame frame1
XmForm form3
XmScrollBar sbl
XmDrawingArea dam
XmScrollBar sbr
XmFrame frame2
XmForm form4
XmForm form2
XmScrollBar sb
XmForm form21
XmFrame frame3
XmLabel fnamel
XmFrame frame31
XmTextField linenuml
XmForm form22
XmFrame frame4
XmLabel fnamer
XmFrame frame41
XmTextField linenumr
XmDrawingArea textl
XmDrawingArea textr
XmScrollBar sbh
XmDialogShell version_popup
XmMessageBox version
XmLabelGadget symbol
XmLabelGadget
XmSeparatorGadget separator
XmPushButtonGadget OK
XmPushButtonGadget Cancel
XmPushButtonGadget Help
XmDialogShell manualpage_popup
XmForm manualpage
XmPanedWindow pane
XmScrolledWindow help_textSW
XmScrollBar vbar
XmText help_text
XmForm form2a
XmPushButton OK
XmSash sash
XmSeparatorGadget separator
XmSash sash
XmSeparatorGadget separator
XmDialogShell legend_popup
XmForm legend
XmPanedWindow pane
XmRowColumn rc
XmLabel label1
XmLabel label2
XmLabel label3
XmLabel label4
XmLabel label5
XmForm form2a
XmPushButton OK
XmSash sash
XmSeparatorGadget separator
XmSash sash
XmSeparatorGadget separator
XmDialogShell werror_popup
XmMessageBox werror
XmLabelGadget symbol
XmLabelGadget
XmSeparatorGadget separator
XmPushButtonGadget OK
XmPushButtonGadget Cancel
XmPushButtonGadget Help
X RESOURCES¶
- Mgdiff.diffForeground:
- black
- Mgdiff.diffBackground:
- yellow
These colors are for blocks which differ between files.
- Mgdiff.sameForeground:
- black
- Mgdiff.sameBackground:
- grey
These colors are for blocks which are identical between files.
- Mgdiff.insertForeground:
- black
- Mgdiff.insertBackground:
- orange
These colors are for blocks which have been inserted in one file.
- Mgdiff.blankForeground:
- black
- Mgdiff.blankBackground:
- grey66
These colors are for blocks which are for display purposes.
- Mgdiff.selectForeground:
- black
- Mgdiff.selectBackground:
- light slate blue
These colors are for blocks which have been selected by the user.
- Mgdiff.font:
- 7x13bold
Font for displaying text blocks.
- Mgdiff.dragScroll:
- true
Set to true if scrollbar dragging should cause immediate changes in the viewed
text, and false if the view should only change after the scrollbar has been
moved.
- Mgdiff.overview:
- true
Set to true if the file overview section should appear.
- Mgdiff.horzScrollbar:
- true
Set to true if the horizontal scrollbar should appear.
- Mgdiff.linesOfContext:
- 3
Number of lines that should appear above a difference block gotten to using the
Previous or Next commands. Should be greater or equal to zero.
- Mgdiff.manCommand:
- (man mgdiff | col -b) 2>&1
The command (or pipeline) used to produce a formatted manual page without escape
codes.
- Mgdiff.diffCommand:
- diff
The
diff(1) compatible command to use for calculating differences between
text files.
- Mgdiff.diffArgs:
-
The arguments to be provided to the
diff command. This resource can also
be set via the
-args command line option.
- Mgdiff.quitIfSame:
- false
If the two files have no differences (as determined by the
diff command)
then exit immediately without bringing up a window. This resource can also be
set to "true" via the
-quit command line option.
- Mgdiff.filename:
- (stdin)
mgdiff uses this string to display over a file read from standard input.
This resource can also be set via the
-file command line option.
DIAGNOSTICS¶
Returns the exit status generated by the
diff command. This is usually 0
for no differences, 1 for some differences and 2 for errors.
SEE ALSO¶
diff(1),
X(1)
RESTRICTIONS¶
Using
BDrag in the overview area doesn't work well when drag scrolling is
turned off.
Doesn't support monochrome displays.
Input lines longer than BUFSIZ (see /usr/include/stdio.h) are silently
truncated.
The code for parsing and passing arguments to the
diff command assumes
arguments are delimited by white space and does not do any quote processing.
COPYRIGHT¶
Copyright (c) 1994, Daniel Williams
Copyright (c) 2003, Erik de Castro Lopo
See
X (1) for a full statement of rights and permissions.
AUTHORS¶
Daniel Williams (dan@sass.com)
Erik de Castro Lopo (erikd AT mega-nerd DOT com) added "
Save as
Left/Right" and saving both and neither sides.
ACKNOWLEDGEMENTS¶
To Andrew C. Myers for writing
gdiff.