Table of Contents
xdiff - X11/Motif based file comparator and merge tool.
Version 3.4
xdiff is a graphical utility for viewing the differences of
a file and up to four revisions of that file. The text of the files is
presented side by side with their differences aligned and highlighted
in colour for easy identification. xdiff can be used to produce a merged
version combining any or all of the differences. Simple editing features
are also provided.
xdiff [options] path1 [path2 [path3 [path4
[ path5 ]]]]
xdiff options are:
-[Dwbi]
-N <name>
-P <define>
-C <diffCommand>
-R <resultFile>
-tabs <number>
-line <number>
-pattern <regexp>
Options and paths may be specified in any order except
for the -N and -P options which must precede their respective path specification.
- -D
- If there are no differences then exit quietly with exit
code of 0.
- -w
- Passed on to diff(1)
. Ignore whitespace when
comparing files.
- -b
- Passed on to diff(1)
. Ignore trailing
blanks when comparing files.
- -i
- Passed on to diff(1)
. Ignore
case when comparing files.
- -
- Not really an option. Use stdin
as one of the files. See DESCRIPTION below.
- -N <name>
- Specifies the string
to use in place of the file name in the title area. This option only applies
to the next path in the argument list. This is useful if the file is a
temporary one and a more meaningful description is wanted. If not specified
then the file name is used. If input is being read from stdin and no -N
is specified then the string "<stream>" is used.
- -P <define>
- This option specifies
a string to be used in a #if defined #endif placed around text for files
for which no selection has been made. If a value is not specified then
the a symbol FILE<number> is used where <number> represents the position in
the argument list. As with the -N option, this option only applies to the
next path in the argument list. See the description of the File menu for
more information.
- -tabs <number>
- Set the tabWidth resource to the specified
value. When displaying the text, tabs will be expanded to 'number' of spaces.
This overrides the value specified in the resources. This is for display
purposes only and will not affect the resulting output of a merge.
- -C <diffCommand>
- Specify an alternate command to use instead of diff(1)
. Of course it must
produce compatible output.
- -R <resultFile>
- This specifies a file name to
be used as a result file. This file name is used by Save Result button
in the file menu. This allows a operation to use xdiff to produce a file
with a generated name that is different from the input files. This could
be one of the input files if you like.
- -line <lineNumber>
- This specifies
the starting cursor line position. The base file is used as the source
for the line number. This is useful when invoking xdiff repetatively with
different revisions looking for a specific change.
- -pattern <regexp>
- This
specifies a starting search pattern. On startup all lines matching this
pattern will be indicated as such. See Searching below.
The paths supplied on the command line identify the files to be compared.
Each path may be one of, a regular file, a directory or a '-' and are subject
to the following requirements. If a directory is specified then there
must also be at least one regular file. For directory paths the last component
of the first regular file will be appended to the directory to form the
file name. There may be only one path specified as '-' in which case the
input for that path will be read from standard input. The order of the
paths on the command line specifies which area of the display the file
will appear. They will be displayed left to right in the order they appear
on the command line. By convention the first file is the base file and
the others are revisions of that file.
The xdiff screen is divided into
3 main areas. These are, the menu bar at the top of the window, a message
line just below it and a text area occupying the remainder. The text area
is further divided into one text window for each file. A vertical slider
separates the base revision from the other revisions. The text windows
have a window containing the text, a title bar at the top and a horizontal
slider at the bottom. Each text window may be augmented with an area containing
line numbers and all revision text windows may also have a difference
overview display area.
xdiff uses diff(1)
or other program to determine
the differences between the files. The diff program is called once for
each revision with the base file. Differences are highlighted using different
colours for the foreground and background. These may be specified by the
user as described below in the section on user preferences. The vertical
slider that separates the base revision from the others controls the vertical
positioning of all text areas simultaneously. The size of the thumb of
the slider is scaled to represent the amount of text visible in the windows.
When line numbers are displayed they will appear in a window to the left
of each of the text regions. For regions of a file where text is absent
there will be no line number displayed.
When the difference overviews
are displayed they will appear in a window to the right of each of the
revision text window. It's purpose is to show graphically, the number,
location and size of the differences between that revision and the base
file. The overview display consists of two columns representing the files
and their differences. The area in between contains lines joining the
two columns to indicate where the differences occur with respect to the
other file. A small arrow is shown in each column and represents the position
of the cursor line in that file. The lengths of the two columns are proportional
to the lengths of the files they represent.
xdiff has a menu
bar consisting of seven buttons. These are listed below and described in
more detail in the sections that follow.
- File
- Contains commands to save
merged files reload files and to exit xdiff.
- Edit
- Contains undo, redo,
editing, block operation, searching and highlighting commands.
- Options
- Contains flag settings for calling diff(1)
, setting tab widths and controls
for toggling parts of the display.
- Global
- Contains functions that apply
to the entire file.
- Region
- Contains functions that apply to a single difference
region.
- Line
- Contains functions that apply to a single difference line.
- Help
- Interface to the online help.
This menu is used to save
merged text to a file, reloading files and also to exit xdiff. Where there
are menu choices that refer to the Base file, First Revision and Second
Revision in this pulldown menu and others it is meant to be illustrative
of what will appear. Which buttons appear will depending on how many files
are specified on the command line.
- Save as Base File
- Short cut to save
the merged text to the source file of the base file.
- Save as First Revision
- Short cut to save the merged text to the source file of the first revision.
- Save as Second Revision
- Short cut to save the merged text to the source
file of the second revision.
These buttons are displayed as toggle buttons
where their state depends on whether or not you have write permission
for these files. If you have write permission then the toggle button is
selected. The default resources will make it a nice reassuring green colour.
Before a save can be performed all differences must have a selection
or you must have specified one or more -P options as described above in
the options section. If you have not specified any -P options and there
are unselected differences an error message is displayed in the message
line and the cursor line is moved to the first line which does not have
a selection. If you have specified one more -P options then each unselected
region or partial region will be enclosed in #if defined( <symbol> ) #endif
preprocessor statements. If the resource confirmWrite is set to True then
a confirmation dialogue is presented before a save allowing the user to
confirm the write or cancel the operation. The default for the confirmWrite
resource is True. If you save to a file when that file has been read from
the standard input xdiff will write the output to standard output. This
allows xdiff to be used in a filter chain like all well behaved Unix utilities.
After a save to a file, a message will be displayed in the message line
to indicate the status of the save.
- Save As ...
- Save As will present the
user with the Motif file selection box. If the user presses the OK button
then the merged text will be written to the specified file, subject to
the conditions described above.
When writing the regions of common text
using 'Save As ...' the text from the current file is used. The current file
is indicated by the inset tile bar. This may yield surprises if the -w
-b -i flags are used. Although the text is indicated as being the same it
may not be. When using Save Base, First, Second, Third or Fourth the common
text is taken from the same file so as to minimize the problems with inappropriate
white space and case.
- Save Result
- If the user has specified a result file
name on the command line with the -R option the merged text will be written
to the specified result file. As with the Save As function common text
will be taken from the current file.
- Add File...
- You may add an additional
file to the current session. This function will present the user with the
Motif file selection box. Selecting the OK button will load the selected
file. This file will be displayed to the right of the current file. If you
want this new file to become the base file then you can set it as the
Base File by selecting File->Set Base File.
- Replace File...
- Selecting Replace
file will present the Motif file selection box. Selecting the OK button
will replace the contents of the current file with the given file. All
differences will be performed and the display will reflect the new file.
- Delete File
- This will remove the current file from the display. If you
delete the Base File then the First Revision will become the new Base
File.
- Set Base File
- Since file comparisons of revisions are made to the
Base File you may want to change which file is the base file. This function
sets the current file as the base file and places its display on the left.
The current base file will become the first revision. Normally you make
the common ancestor of the revisions the Base File.
- Reload
- This function
can be used to update the display for changed files or changed options
without the need to restart the application. Any needed files will be
reread and any necessary diffs performed. xdiff will attempt to remain
on the same line in the base file after the reload. If there is a starting
search pattern defined then this will be redone after the reload as well.
- Exit
- This is the normal place to exit xdiff. If you have attempted to
save a merged file and that save has failed then a message will appear
in the message line stating that your changes have not been saved. This
is to give you a chance to save your changes by correcting the save problem
or save them to another file. Once the message has appeared then selecting
Exit again will leave xdiff without the warning message.
This
menu contains functions for undo, redo, block operations, searching and
shuffling lines within a difference region.
- Undo
- Undo the last undoable
operation. The undoable operations are selection, split, mark as changed
and edit. The commands Cut Region and Paste Region are not undoable and
will remove the undo history. Cut and Paste are complementary operations
and can be used to undo each other. Previous operations may be undone
by repeating the undo operation.
- Redo
- After an undo, the undone operation
may be restored by using the redo command. Successive operations may be
restored by repeating the redo command.
- Edit
- Minor editinf is provided
using this command. When invoked a dialog box will be displayed with the
text of each file in a separate text edit field. You may edit this text
in the normal fashion.
- Highlight Differences
- Sometimes it is difficult
to see the differences between the revisions. The Highlight Differences
command changes the display for the cursor line to indicate the differences.
It uses the same colour scheme as is used for the line display. The display
for this line will revert to the normal display if you choose highlight
again with the cursor line on that line or when you select another line
for highlight display.
- Mark as Changed
- Because of the way diff(1)
works
some regions of change will be broken into two or more regions. You may
wish to treat it as one in your selection and editing. They may be merged
into a single region by first marking the region you wish to change by
going to one end of the region and using Set Mark and then going to the
other end of the desired region. This will create the marked range to be
used for the Mark as changed commad. The command Mark as Changed will change
this marked range into one region of type Changed.
- Add Edit Marker
- For
really complicated merges it may be easier to perform the merging in your
favourite text editor as a post process. Using Add Edit Marker will place
a new item in the difference list with the text defined by the resource
"*editMarker". This new item will automatically be selected. After you save
your merges you may invoke your favourite editor and search for the inserted
string to make your chages.
- Set Mark
- The cursor line is set as the mark
line. When the cursor line is moved the marked region is extended to the
new position of the cursor line. This region is used by the commands Cut
Region, Copy Region, Mark as Changed, line selection and line splitting.
The extent of the marked region is indicated with special Marked colours.
See the section on user preferences on how to change this colour from
the default of white text on blue background. The marked region is toggled
off after any command that uses the mark. It may also be toggled off by
selecting Set Mark again.
- Copy Region
- Copy the marked region to xdiff's
cut buffer. The Marked region is cleared after the copy.
- Cut Region
- Delete
the marked region. Save it in xdiff's cut buffer.
- Paste Region
- Insert the
contents of xdiff's cut buffer after the cursor line. The cut buffer is
cleared after the paste operation.
- Search ...
- Search will present a dialogue
box containing searching parameters. See the section "Search Dialogue"
for a complete explanation.
- Search Next
- After search parameters have been
entered through the Search Dialogue the Search Next command will move
the cursor from its current position to the next match. If there are no
more matches below the cursor line then the cursor will remain where it
is and a message will be displayed in the message line "No match to bottom".
- Search Previous
- As above but the cursor will move from its current position
to the previous match. If there are no matches above the cursor line then
the cursor will remain where it is and a message will be displayed in
the message line "No match to top".
- Highlight Differences
- Sometimes it
is difficult to see the differences between the revisions. The Highlight
Differences command changes the display for the cursor line to indicate
the differences. It uses the same colour scheme as is used for the line
display. The display for this line will revert to the normal display if
you choose highlight again with the cursor line on that line or when you
select another line for highlight display.
- Mark as Changed
- Because of
the way diff(1)
works some regions of change will be broken into two or
more regions. You may wish to treat it as one in your selection and editing.
They may be merged into a single region by first marking the region you
wish to change by using Set Mark and some cursor movement. The command
Mark as Changed will change the marked range into one region of type Changed.
- Shift Up
- Shift up is used to move lines up with respect to the other
files. You may only shuffle lines from regions of changed text. This can
aid in making the desired selections. You must first change the current
file to the file you wish to modify. This may be done by clicking on the
title area at the top of the text region or by making a selection in the
desired file or by adding a translation using the file action function.
Place the cursor line on the bottom line that you want to move up. Use
Shift Up to move the current line and all adjacent lines up one line.
The cursor line and the adjacent lines are moved up in relation to the
other files. If there is no more room in the region then space is created
at the top of the region.
- Shift Down
- Like Shift Up but the text goes down
instead.
This menu allows the user to change the options
used in the difference algorithm. The visibility of portions of the display
may also be toggled using commands in this menu.
- Ignore Trailing Blanks
- Toggles the state of the ignore trailing blanks flag. The reload command
can then be used to update the differences with the changed options.
- Ignore
Whitespace
- Toggles the state of the ignore whitespace flag. The reload
command can then be used to update the differences with the changed options.
- Ignore Case
- Toggles the state of the ignore case flag. The reload command
can then be used to update the differences with the changed options.
- Tabs
4
- Specifies that tabs should be expanded to 4 spaces.
- Tabs 8
- Specifies
that tabs should be expanded to 8 spaces.
- Set Tabs...
- Presents the user with
a dialogue to specify the width of tabs.
- Toggle Numbers
- This will toggle
the display of line numbers. When line numbers are displayed each text
area will be augmented by another window to the left of the text area.
This new window area will contain the line numbers.
- Toggle Overview
- This
will toggle the display of the overview windows. When the overview windows
are displayed each text area except the base file will be augmented by
another window to the right of the text area. This new window area will
contain the overview of the differences between that revision and the
base file..
- Scroll Lock
- When set, this toggle causes the horizontal scroll
bars to synchronize and move together.
- Center Differences
- When set, xdiff
will attempt to center the cursor line after going to the next or previous
difference. When not set, xdiff will try to maintain the current cursor
position.
- Backup Files
- When set, xdiff will attempt to create a backup
file before overwriting an existing file.
- File Exclusive
- When viewing
the differences of more than two files it is sometimes desirable to go
to a difference that is due to a specific revision. When the state of fileExclusive
it True, the next/previous functions ignore the differences due to other
files. This does not apply when moving between differences on the highlighted
line.
- Auto Select Splits
- The region and line split operations can be made
to automatically select the new regions or lines. When this options is
false no automatic selection will take place. However, any selection on
the split region will remain.
- Save Unselected
- Normally the user is required
to make a selection for all the differences between the revisions or specify
one or more -P options on the command line. This requires that you know
ahead of time that this will be required. For those times when you didn't
add the -P on the command line and you would like to save some unselected
differences you can use the "Save Unselected" option to allow the save.
The default preprocessor symbols will be used if none have been specified.
This menu contains operations that affect the entire file.
For the selection command below they will only be applied to the differences
that do not yet have a selection. This allows a few choices to be made
and then the rest of the selections can be done globally. To select all
the differences from a file after some selection have been made first
use Global->Remove Selection and then the appropriate global selection.
- Select Base File
- Selects all the difference regions from the base revision.
- Select First Revision
- Selects all the difference regions from the second
revision.
- Select Second Revision
- Selects all the difference regions from
the third revision.
- Select Nothing
- All difference regions are not selected.
Only common text will be included in any merged output.
- Remove Selection
- Removes all selections that have been made.
- Merge
- When there are two or
more revisions the Merge function can be used to select all non overlapping
differences. Overlapping differences will remain unselected. You can use
the Next Unselected function in the popup to find these differences and
choose an appropriate course of action. As with the other global selection
functions it will not change the selection of any difference that already
has a selection.
The functions of the Region Menu use the
location of the cursor line to specify the region for which the function
is to be performed. These functions will only work when the cursor line
is on a difference region. Similar to the global operations, selections
made to a region will not alter selections of individual lines. In this
way you can make a few line based selections and then select the remainder
of the region with the region selection. To select the entire region of
a file after line selections have been made from other files simply remove
the selection of the region and then make the desired selection. If a region
has been entirely selected from one file then it is not necessary to remove
the selection to select another file.
- Select Base File
- The entire difference
region from the base file is selected.
- Select First Revision
- The entire
difference region from the first revision is selected.
- Select Second Revision
- The entire difference region from the second revision is selected.
- Select
Nothing
- No file region is selected. No text from any file in this region
will be included in the merged output.
- Remove Selection
- Any previous selection
made to this region will be removed.
- Split Base
- In the case when the text
has changed between the files and it is desired to have more than one
difference appear in the merged output split can be used to create two
difference regions so that each may be selected individually. Split Base
will extract all the non empty text from the base file in the difference
region and place it a new region above the existing one. Any line selections
that had been previously made to the region will remain in both regions
after the split. The new region will then be selected automatically. This
region selection will not override the any line selection as described
above. If the existing region now only contains the text from one file
then it too is automatically selected. The selections and the split are
entered into the undo list separately so that they may be undone separately.
Because of this it may require three undos to completely undo the split
operation.
- Split First
- Same as Split Base except that the text from the
first revision is listed first.
- Split Second
- Same as Split Base except
that the text from the second revision is listed first.
This
menu's functions use the location of the cursor line to specify the line
for which the operation is to be performed. These functions will only
work when the cursor line is on a difference line.
- Select Base
- The line
from the base file is selected.
- Select First
- The line from the first revision
is selected.
- Select Second
- The line from the second revision is selected.
- Select Nothing
- The cursor line for all files is not selected and so no
line will be included in the merged output.
- Remove Selection
- Any previous
selection made to this line will be removed.
- Split Base
- Same as Split
Base in the Region Menu above except that it only operates on the current
line. If a group of lines are marked using the Set Mark from the Edit
Menu then all of the marked lines are treated as a block and split as
a unit. Shift Up and Shift Down from the Edit Menu may be used to align
the lines prior to the split.
- Split First
- Same as Split Base except that
the text from the first revision is listed first.
- Split Second
- Same as
Split Base except that the text from the second revision is listed first.
- On Context
- This menu can be used obtain help for any widget
in the main window. Selecting the help on context button will cause the
cursor to change to a question mark. Move this cursor to any of the widgets
and click. A netscape window will be created and the appropriate section
of the man page will be displayed.
- HTML man page
- Help for xdiff is displayed
using netscape. The menu entry will display the man page in your current
netscape session or a new one started if it is not running.
- What's New
- This describes new features in this release of xdiff.
- About xdiff
- Provides
a brief synopsis of xdiff.
xdiff can be used to merge the
differences from the given files into another or to overwrite one or all
of the original files. To select the desired differences the user interacts
as follows. Note that this description assumes the default translations
described below.
With the pointer in one of the text windows and pressing
the left button the cursor line moves to the line under the pointer. If
this line is in a difference region then the region from that file is
selected.
Pressing the middle button with the pointer in any of the text
windows will move the cursor line to the line under the pointer. If this
is within a difference region then a selection of only the cursor line
is made. This allows a finer level of selection of which text will appear
in the merged output.
Holding the Shift key while pressing a button will
cause the region or line, with left or middle button respectfully, to
have it's selection removed.
Holding the Alt key while pressing the button
will cause the region or line, as described above, to have no selection.
No text from any file will appear in the merged output.
If some lines
have been selected, selecting the region will not override any of the
line selections. With this you may make a few line selections and then
easily select the rest from another file. To select the entire region
after having made some line selections you will need to unselect the region
to first clear the line selections and then select the desired region.
This is also the case for global selection. Global selection will not
override any of the selections already made. To select the entire file
after having made some selections you will need to unselect everything
to first clear all selections and then select the desired file.
These
selections may also be performed by making the selection in the line number
areas if they are displayed.
These interactions are defined by translations
in the application defaults file. See the section below describing the
translations and how they may be customized.
Pressing the right button
while in any of the text windows will post a popup menu. This popup's methods
are to move to other difference regions. Accelerators may be attached to
provide quick navigation using the keyboard. Be careful not to define an
accelerator for these buttons and also a translation for the the same
function or you will skip over every other difference since they will
both be performed.
The selections in this popup are as follows.
- Next Difference
- Go to the first line of the next difference region.
- Previous Difference
- Go to the last line of the previous difference region.
- Next Unselected
- Go to the next difference line that is still unselected.
- Previous Unselected
- Go to the previous difference line that is still unselected.
- Next Selected
- Go to the next difference line that is selected.
- Previous Selected
- Go
to the previous difference line that is selected.
When the File Exclusive
flags is set through the Option Menu or the resources then next or previous
will mean that it applies only to the current file. When the cursor line
is on the highlighted line then the display will scroll horizontally to
put the difference within the line at the left edge of the window. This
can be useful then finding differences within long lines.
Pressing any
button while the pointer is in an overview area will move the cursor line
to the relative position in the file indicated by the pointer position.
If the pointer is in the left half of the overview window the line will
be determined from the base file and from the revision corresponding to
the overview if the pointer is in the right half. The cursor line will
then be displayed in the center of the text windows. If the pointer is
dragged while the button is down the cursor line will follow the pointer.
A simple editing dialogue is included in xdiff to allow
minor changes to text. It is also a back door to X cut and paste. The edit
dialogue consists of a Motif text field for each file. The text of the
current line is placed in these text fields. They may be edited in the
normal fashion. However, you may not add a new line. Once you are satisfied
with your changes the Apply button will cause the changes to be reflected
in the text windows. The Reset button will revert to the state when the
edit dialogue was entered or the last time the Apply button was pressed.
The Close button will dismiss the edit dialogue.
While the edit dialogue
is up it does a pointer grab so interaction in the main xdiff window is
not possible. Any edits may be undone after the edit window is closed.
Since you cannot specify the spacing of tabs in the Motif text field
they are always expanded to 8 spaces.
A searching dialogue
is available in xdiff to allow the user to locate specific lines in the
files being compared. The main elements of the searching dialogue are
a menu bar to allow the user to specify the type and scope of the search,
handy buttons to search next and previous matches and an important search
pattern entry field.
The searching dialogue menu bar has two pull downs,
one to set the search type and one to set the search scope.
The Type pulldown
has buttons to specify the type of search to be performed.
- Regular Expression
- The specified search pattern will be interpreted as full regular expressions.
- Literal Case Sensitive
- The specified search pattern will be interpreted
as literal text where case is respected.
- Literal Case Insensitive
- The
specified search pattern will be interpreted as literal text where case
is ignored.
- Line Numbers
- The specified search pattern will be interpreted
as a line number.
The Scope pulldown sets the scope of the search. The
search will only be performed for the files indicated by active toggle
buttons in this menu.
- Search All
- A handy button to turn the search on for
all files.
- Search None
- A handy button to turn the search off for all files.
- Search Base File
- Toggle the search state for the Base file.
- Search First
Revision
- Toggle the search state for the first revision.
- Search Second
Revision
- Toggle the search state for the second revision.
The user enters
the search pattern into the text field of the search dialogue and presses
the Search button or hits the return key.
The search dialogue also contains
two buttons to search for the next or previous match. They do what you
would expect them to. The search will not wrap using these buttons as it
will when using the search button or return key.
At the bottom of the
searching dialogue are three buttons. The Search button will initiate
the search of the specified type in the specified file scope. A small diamond
will appear in the overview area for each line that matches the search
pattern. To move to a match you may click on one of the diamonds in the
overview area or use the Search Next or Search Previous buttons. There
are Search Next and Search Previous buttons in the Edit menu for use when
the search dialogue is not displayed. The Clear button will clear the
search pattern and reset all the flags on all lines matching the previous
pattern. The Close button will dismiss the search dialogue leaving the
search pattern and match flags intact.
Some of
the behaviour of xdiff is specified by X event translations. These translations
invoke one of four actions functions to perform their function. To perform
selections using the mouse we can write a translation using the action
selection(). Only button down events may to used in translations using
the selection action. The location in the button event is used to determine
the cursor location.
The selection action takes two parameters. First is
the operation. There are three operations that may be specified.
- select
- This specifies that the entity under pointer should be selected.
- unselect
- This will remove any selection for the item under the pointer.
- delete
- This selects no file side. The item will not appear in the merged output.
The second parameter specifies the zone of influence for the selection.
This parameter may be either region or line.
- region
- We make selection for
the entire region under the pointer.
- line
- The selection is applied only
to the line under the cursor.
The next action function we can talk about
is the cursor action. This one moves the cursor line around a bit. This
action takes only one argument and can be one of five things.
- up
- The cursor
line is moved up one line.
- down
- The cursor line is moved down one line.
- top
- The very top is where you will find the cursor line after this.
- bottom
- You have sunk to the end of the file with this.
- high
- Moves the cursor
line to the top of the display if it can. Mimics the H function of vi.
- middle
- Moves the cursor line to the middle of the display if it can. Mimics
the M function of vi.
- low
- Moves the cursor line to the bottom of the display
if it can. Mimics the L function of vi.
- search
- This action will search
all files for a regular expression in a specified direction. So i lied.
This action takes two additional arguments. The second argument of this
action is either 'forward' or 'backward'. The last argument is the regular
expression to match. The following is a translation that can be used to
search up for the top of a C function. ~Shift<Key>-: cursor(search
backward "^{")\n\
- return
- This action will return the cursor to the location
where the previous command was invoked. For example if you have just performed
the next difference command and then you go to the top of the file you
can then use cursor( return ) to return to your previous position.
The
next action is called scroll(). The first argument specifies the direction
to scroll and an optional second argument specifies the amount to scroll.
With the vertical scrolling the cursor line will remain in the same location
if possible.
- up
- The text is scrolled up by the specified amount.
- down
- The text is scrolled down by the specified amount.
- left
- The text is scrolled
left by the specified amount.
- right
- The text is scrolled right by the
specified amount.
The amount to scroll can be one of three values.
- page
- The text is scrolled height in lines minus one vertically or the width
in characters minus one horizontally of the text window. The is the default
scrolling amount.
- half
- The text is scrolled half the height in lines vertically
or half the width in characters horizontally of the text window.
- 1
- The
text will scroll one line vertically or one character horizontally.
- end
- This will scroll as far as possible in the desired direction.
The last
action is the file action and is used to set the current file. This action
takes only one argument.
- next
- This set the current file to the next file
to the right and will loop back to the first file.
- prev
- This set the current
file to the previous file to the left and will loop back to the last file.
The default translations for xdiff are listed below. The arguments to
the actions can be upper or lower case. In fact only the first letter
of each argument is significant.
*mainForm*XmDrawingArea.translations:#override\n\
~Alt ~Shift<Btn1Down>: selection(select region)\n\
Shift<Btn1Down>:
selection(unselect region)\n\
Alt<Btn1Down>:
selection(delete region)\n\
~Alt ~Shift<Btn2Down>: selection(select
line)\n\
Shift<Btn2Down>: selection(unselect line)\n\
Alt<Btn2Down>: selection(delete line)\n\
<Key>osfBeginLine:
cursor(top)\n\
<Key>osfEndLine: cursor(bottom)\n\
<Key>osfUp: cursor(up)\n\
<Key>osfDown:
cursor(down)\n\
~Ctrl<Key>osfPageDown: scroll(down)\n\
~Ctrl<Key>osfPageUp: scroll(up)\n\
For those of us who don't
think the arrow keys are convenient enough to be useful, after all you
have to move your hands from the home row, we can add the motion keys
from our favorite editor to the translations. These work well for us vi
users.
~Shift<Key>j: cursor(down)\n\
~Shift<Key>k:
cursor(up)\n\
Ctrl<Key>e: cursor(down)\n\
Ctrl<Key>y: cursor(up)\n\
~Shift<Key>g:
cursor(top)\n\
Shift<Key>g: cursor(bottom)\n\
Ctrl<Key>b: scroll(up)\n\
Ctrl<Key>f:
scroll(down)\n\
To move between differences we can use the
popup in the text areas. When using the keyboard we can add accelerators
for the buttons in that popup. This requires that the pointer be placed
in the text area for the accelerators to be invoked. It can be annoying
when the xdiff window comes up and the pointer is on the scroll bars or
the line number areas and the accelerators are unavailable. To solve this
we can add translations to the XmDrawingArea translations above and augment
the translations for the scroll bars with the following.
~Alt Shift<Key>n:
cursor(prev)\n\
~Alt ~Shift<Key>n: cursor(next)\n\
Alt Shift<Key>n: cursor(prev unselected)\n\
Alt ~Shift<Key>n:
cursor(next unselected)\n\
Do not add accelerators to the
drawing area popups and have these additional translations at the same
time as the cursor will skip 2 differences instead of just one.
These
are the translations that i have in my application defaults file. This
is so that i can use xdiff entirely from the keyboard.
*mainForm*XmDrawingArea.translations:#override\n\
Alt<Btn1Down>: selection(delete region)\n\
Alt<Btn2Down>:
selection(delete line)\n\
Shift<Btn1Down>:
selection(unselect region)\n\
Shift<Btn2Down>: selection(unselect
line)\n\
~Alt ~Shift<Btn1Down>: selection(select region)\n\
~Alt ~Shift<Btn2Down>: selection(select line)\n\
<Key>osfBeginLine:
cursor(top)\n\
<Key>osfEndLine: cursor(bottom)\n\
~Ctrl<Key>osfPageDown: scroll(down)\n\
~Ctrl<Key>osfPageUp:
scroll(up)\n\
<Key>osfUp: cursor(up)\n\
<Key>osfDown: cursor(down)\n\
Ctrl<Key>y:
cursor(up)\n\
Ctrl<Key>e: cursor(down)\n\
~Shift<Key>k: cursor(up)\n\
~Shift<Key>j:
cursor(down)\n\
Shift<Key>g: cursor(bottom)\n\
~Shift<Key>g: cursor(top)\n\
Ctrl<Key>d:
scroll(down)\n\
Ctrl<Key>u: scroll(up)\n\
~Alt Shift<Key>n: cursor(prev)\n\
~Alt ~Shift<Key>n:
cursor(next)\n\
Alt Shift<Key>n: cursor(prev
unselected)\n\
Alt ~Shift<Key>n: cursor(next unselected)\n\
~Shift<Key>-: cursor(search backward "^{")\n\
~Shift<Key>=:
cursor(search forward "^{")\n\
Shift<Key>space:
file(next)\n\
~Shift<Key>space: file(previous)\n\
*mainForm*XmScrollBar:#override\n\
<Key>osfBeginLine:
cursor(top)\n\
<Key>osfEndLine: cursor(bottom)\n\
~Ctrl<Key>osfPageDown:
scroll(Down)\n\
~Ctrl<Key>osfPageUp: scroll(Up)\n\
<Key>osfUp: cursor(up)\n\
<Key>osfDown:
cursor(down)\n\
Ctrl<Key>y: cursor(up)\n\
Ctrl<Key>e: cursor(down)\n\
~Shift<Key>k:
cursor(up)\n\
~Shift<Key>j: cursor(down)\n\
Shift<Key>g: cursor(bottom)\n\
~Shift<Key>g:
cursor(top)\n\
Ctrl<Key>d: scroll(down)\n\
Ctrl<Key>u: scroll(up)\n\
~Alt Shift<Key>n:
cursor(prev)\n\
~Alt ~Shift<Key>n: cursor(next)\n\
Alt Shift<Key>n: cursor(prev unselected)\n\
Alt ~Shift<Key>n:
cursor(next unselected)\n\
~Shift<Key>-:
cursor(search backward "^{")\n\
~Shift<Key>=: cursor(search
forward "^{")\n\
Shift<Key>space: file(next)\n\
~Shift<Key>space:
file(previous)\n\
In addition to customizing
the translations we can specify resources to change the colours and fonts
used by xdiff. We need to define some terminology first. The differences
obtained from diff(1)
can be classified into 4 types.
- Common
- Common text
which is present in all files.
- Only
- Only text is text that appears only
in one file.
- Absent
- When text is missing from a file the void in the other
files is called Absent. This always accompanies Only text.
- Changed
- Text
which has been changed between the files is called Changed Text.
- Same
- A special case of Changed text is Same. This is used for text in a changed
region that is the same as the base file. The base file will also use this
colour when all other files are the same or are absent. This allows an
additional colour clue as to the extent of the changes.
Unselected text
will use the types above. Once a selection has been made the following
types will apply.
- Selected
- When the user has selected one of the differences
then that will be selected the others will become deleted.
- Deleted
- This
text is not desired in the merged output. If the user selects one file
the others will be marked as deleted. This will also be used to mark all
files when the selection type is select nothing.
- Marked
- This is to indicate
the region between the mark line and the cursor line. This indicated the
text to be used for the Cut or Copy operation. This overrides any of the
colours above. These names are used to form X11 resources names to determine
the users preferences.
Each of these categories may have different colours
for foreground and background. They may also have a different font. i have
found that using a bold font for selected text makes it stand out quite
well. Any unspecified fonts will default to the font for fontCommon. To
specify the foreground resources name prefix the name with 'foreground'
the background is specified by prefixing the name with 'background'. To specify
the font, prefix with 'font'. From the app-defaults file the Common Text
is specified with.
*fontCommon: *-clean-medium-r-normal-*-14-*
*foregroundCommon:
black
*backgroundCommon: grey
The cursor colour may be specified
using the resource 'cursorColour' This colour is used to outline the cursor
line in the text windows and the outline of the triangular indicator in
the overview area.
Lines that match the pattern specified in the search
window may be outlined in a different colour to indicate the match. The
resource used to specify this is 'matchColour' if not specified the cursorColour
is used.
The user interaction of xdiff may be customized
by setting additional resources through an app-defaults file or by using
the standard -xrm option on the command line. The following resources may
be set by the user. The defaults are listed with each option.
- confirmWrite
- If True, a confirmation dialogue is presented before a save allowing the
user to confirm the write or cancel the operation. The default is True.
- confirmQuit
- If True, a confirmation dialogue is presented before xdiff
exits allowing the user to cancel the operation. The default is True.
- overview
- If True xdiff will display a difference overview window to the
right of each of the revision text windows. The default is True. The value
may be toggled through the Options menu.
- lineNumbers
- If True xdiff will
display line numbers on startup. The default is True. The value may be
toggled through the Options menu.
- ignoreWhitespace
- If True xdiff will
ignore whitespace when comparing files. The default is False. The value
may be toggled through the Options menu.
- ignoreTrailing
- If True xdiff
will ignore trailing blanks when comparing files. The default is False.
The value may be toggled through the Options menu.
- ignoreCase
- If True
xdiff will ignore case when comparing files. The default is False. The
value may be toggled through the Options menu.
- centerDiffs
- If True, xdiff
will attempt to center the cursor line after going to the next or previous
differences. If False, xdiff will try to maintain the current cursor position.
The default False. The value may be toggled through the Options menu.
- backupFiles
- When True, xdiff will attempt to backup files before overwriting
them. The default False. The value may be toggled through the Options menu.
- backupSuffix
- This resource specifies a suffix which will be added to
the file name to form the backup file name. If no value for backupSuffix
is found in the resources then the value ".bak" will be used.
- tabWidth
- When displaying the text, tabs will be expanded to the number of spaces
as specified by this resource. The default is 8. The value may be set
through the Options menu or on the command line thought the -tabs option.
- diffCommand
- Specify an alternate command to use instead of diff(1)
. The
default is "diff". The value may be set on the command line thought the
-C option.
- startLine
- This specifies the initial cursor line. Useful for
iterative comparisons through a number of revisions. The default is line
1. The value is normally set thought the command line argument with the
-line option.
- startSearch
- Specifies an initial search pattern. Also useful
for iterative comparisons. The default is "". The value is normally set
thought the command line argument with the -pattern option.
- overviewWidth
- This specifies the width of the overview windows. The default is 30.
- scrollLock
- When True, moving a horizontal scroll bar will affect all text window
simultaneously. The default is True. The value may be toggled through the
Options menu.
- slideDiffs
- When invoking diff on multiple files the same
difference may not be aligned with respect to the base file. When set this
resource will slide the difference region down while the top line of the
region matches the line directly following the region. This produces fewer
difference regions and makes selection much easier. The default is True.
- fileExclusive
- When viewing the differences of more than two files it
is sometimes desirable to go to a difference that is due to a specific
revision. When the state of fileExclusive it True then using the next/previous
functions the differences due to other files are ignored. This does not
apply when moving between differences on the highlighted line. The default
is False. The value may be toggled through the Options menu.
- splitSelection
- The value of this resource specifies whether or not the region and line
split operations automatically select the new regions or lines. When this
options is True automatic selection will take place. Regardless of the
value of this resource any selection on the split region will remain.
The default is True. The value may be toggled through the Options menu.
- overviewWidth
- This specifies the width of the overview windows. The default
is 30.
- editMarker
- This specifies the string to be used by the Add Edit
Marker command. The default is ">>> edit marker <<<"
- saveUnselected
- Normally
all differences must have a selection before a save can be performed.
When saveUnselected is set the requirement is not required. If there are
unselected differnences they will be enclosed in #if defined / #endif
pairs. The default is False. The value may be toggled through the Options
menu.
- allocateColourMap
- Since xdiff allocates it's own colour map there
will be some annoying flashing as the hardware colour map gets changed
when focus changes. The allocation of the colour map is controlled by the
resource allocateColourMap. The default is True. Set it to False if you
don't want this behaviour.
xdiff uses temporary files when reading
from stdin or performing line highlighting. These files will be located
in $TMPDIR if it is defined otherwise it will be located in /usr/tmp.
The file name will be of the form xdiffXXXXXX.
Application defaults for
xdiff can be found in /usr/lib/X11/app-defaults/XDiff.
If you edit
a copied line then all copies of that line are are affected by the edit.
The colour of a region in the overview is determined by the first line
of the region. As a result line based selections will not show up in the
overview area.
gdiff(1)
, diff(1)
.
Discussions about xdiff may
be directed to comp.windows.x.apps
Rudy Wortel <rudy@aw.sgi.com>.
Table of Contents