.ig
Copyright (c) 2016-2019, Carsten Kunze <carsten.kunze@arcor.de>

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
..
.Dd July 6, 2022
.Dt VDDIFF 1
.Sh NAME
.Nm @vddiff@
.Nd text terminal directory diff tool
.Sh SYNOPSIS
.Nm
.Op Fl u Op Ar "RC_file"
.Op Ar OPTIONS
.Op Fl F Ar file_name_pattern
.Op Fl G Ar file_content_pattern
.Op Fl P Ar last_wd_file
.Op Fl t Ar diff_tool
.Op Fl v Ar view_tool
.Op Fl -
.Oo
.Ar directory_1 Ns Li | Ns Ar file_1
.Op Ar directory_2 Ns Li | Ns Ar file_2
.Oc
.Sh DESCRIPTION
.Nm
stands for
.Dq Vim directory diff .
It is a simple text terminal directory diff tool using
.Xr vim 1
for the actual diff operation.
(If vim is not installed,
.Dq Li diff Ar file_1 Ar file_2 Li | less -Q
is used instead.
Other diff tools can be configured as well.)
A file browser displays the names found in the directories
given on the command line.
Unless option
.Fl r
is used,
directories are not compared before they are entered.
.Pp
Compressed files are automatically decompressed into
a temporary directory before the diff tool is started.
These files are detected by their file name extension,
the file contents are not (yet) checked.
Currently the following file name extensions are
supported:
.Li .bz2 ,
.Li .gz ,
.Li .rar ,
.Li .tar ,
.Li .tbz ,
.Li .tgz ,
.Li .txz ,
.Li .xz ,
.Li .zip ,
and
.Li .Z .
.Li .jar ,
.Li .ods
and
.Li .odt
are also treated as archives.
If a view tool is set for them using the
.Cm ext
command,
key
.Sq Li o ,
.Dq Li ol ,
or
.Dq Li or
must be used to open the tool.
In
.Sy bmode
and
.Sy fmode
(see below) also key
.Aq Cm ENTER
opens the configured tool.
.Pp
If one argument is a directory and the other is a
non-directory, a diff is done between the non-directory
and it's last path component within the directory.
If
.Nm
is started with only one or no argument
it behaves like a simple single directory view
file browser (a mode called
.Sy bmode
whereas the normal mode is called
.Sy diff mode ) .
By use of marks files and directories can be compared in bmode.
If less than two arguments are used in two-column mode
kind of a file manager mode (called
.Sy fmode )
is started.
This mode does not support global marks.
All
.Nm
modes are explained in section
.Sx VDDIFF MODES .
.Pp
Symbols are printed in two columns before the names
which have the following meaning:
.Pp
First column (or middle bar in two-column mode): Difference type
.Bl -column -offset indent ".Sq Li !"
.It So Li " " Sc Ta "Directory, equal files or different file types"
.It So Li ! Sc Ta "Different files or links (or directories with option" Fl r )
.It So Li < Sc Ta "Files found in first directory only"
.It So Li > Sc Ta "Files found in second directory only"
.It So Li = Sc Ta "Files have same i-node"
.It So Li - Sc Ta Error
.It So Li X Sc Ta "Two-column mode: Different file type"
.El
.Pp
Second column (or first column in two-column mode and
.Sy bmode ) :
File type
.Bl -column -offset indent ".Sq Li !"
.It So Li /   Sc Ta Directory
.It So Li " " Sc Ta "Plain file"
.It So Li @   Sc Ta "Symbolic link"
.It So Li c   Sc Ta "Character device"
.It So Li b   Sc Ta "Block device"
.It So Li =   Sc Ta Socket
.It So Li |   Sc Ta FIFO
.It So Li ?   Sc Ta "Unknown file type"
.It So Li !   Sc Ta "Different file type"
.El
.
.
.
.Sh OPTIONS
.
.
.
.Bl -tag -width 12n
.
.It Fl u Op Ar filename
Skip reading the initialization file at start-up.
If
.Fl u
is used, it must be the very first option.
If an optional
.Ar filename
is supplied, this file is read instead of the default
initialization file
.Pa ~/.@vddiff@rc .
.Ar filename
needs to be separated with white space from
.Fl u .
.
.It Fl -
All following arguments (if any) are not recognized as options
even when starting with a
.Sq Fl "" .
.
.It Fl A Oo Fl psW Oc Ar source_file_or_directory Ar ... Ar destination_file_or_directory
Recursively copy source arguments to destination argument.
. Bl -tag
. It Fl p
Be verbose.
. It Fl s
Print summary.
. It Fl W
Force overwrite (don't ask).
. El
.
.It Fl a
Preserve all attributes on copy except file type
(following links is selected with option
.Fl l
or RC command
.Cm followlinks ) .
.
.It Fl B
Force two-column file browser mode even if two arguments are given.
Normally diff mode is started with two arguments.
Even if it is possible to change to browse mode with key
.Sq Li # ,
it may take a long time until the (not needed) diff is done.
So
.Fl B
avoids diff mode at all.
.It Fl b
Disable color.
.It Fl C
Don't compare file contents, only test for file existence.
If differences regarding the existing of files are of interest
in a directory with many huge files,
it may take very long to compare their contents.
.Fl C
does any tests but always assumes that two existing files are equal.
.Pp
Alternatively it is also possible to type
.Sq Li %
to ignore file contents for the further directory diff.
.Sq ( Li %
should pressed only short and one time.
The comparison of the current file continues which may take a while,
but further files are not compared.)
.It Fl c
Show only directories which exist in both trees
and really different files.
.begin_comment
.Pp
One sided directories are not shown\(emas one sided files.
File type differences are not shown too.
Normal directories need to be shown to enable browsing.
.Pp
.end_comment
If also
.Fl r
is used only those directories are shown
which contain differences.
.It Fl D Oo Fl psW Oc Ar file_or_directory Ar ...
Recursively delete given arguments from disk.
. Bl -tag
. It Fl p
Be verbose.
. It Fl s
Print summary.
. It Fl W
Force delete (don't ask).
. El
.It Fl d
Use
.Dq Li diff $1 $2 | less -Q
as diff tool.
(If a specific diff tool (other than
.Li vim -d )
should be used in general, it is recommended
to configure it with the RC file option
.Sy difftool ,
see section
.Sx CONFIGURATION FILE ~/.@vddiff@rc
below.)
.It Fl E
Use extended regular expressions.
.It Fl e
Use basic regular expressions.
.It Fl F Ar pattern
Display only file names which match
.Ar pattern ,
which is normally a case ignoring basic regular expression.
With
.Fl E
extended regular expressions are enabled,
with
.Fl I
case-sensitive matching is used.
The pattern match is only applied to non-directories.
To display only directories which contain matching
files add option
.Fl r
(command
.Do Nm
.Fl rF Ar pattern Ar directory Dc
works in bmode somehow similar to
.Dq Nm find Ar directory Fl name Ar pattern ) .
Key
.Sq Li E
toggles display of all files and directories or
matching files only.
The pattern can be removed with the
.Dq Li :nofind
command.
.It Fl f
Normally directories are displayed on top.
With this option files are displayed first.
.
.It Fl G Ar pattern
Display only files which contain
.Ar pattern
(which is normally a case ignoring basic regular expression).
With
.Fl E
extended regular expressions are enabled,
with
.Fl I
case-sensitive matching is used.
The pattern match is only applied to regular files.
To display only directories which contain matching
files add option
.Fl r
(command
.Do Nm
.Fl rG Ar pattern Ar directory Dc
works in bmode somehow similar to
.Dq Nm grep Fl r Ar pattern Ar directory ) .
Key
.Sq Li E
toggles display of all files and directories or
matching files only.
Option
.Fl G
can be combined with option
.Fl F .
For example
.Pp
.Dl @vddiff@ \-rF '\(rs.[1-9]$' \-G '/usr'
.Pp
finds all manpage source files which contain
absolut path names.
Option
.Fl G
can be used multiple times, in this case
.Sy all
.Ar pattern Ns No s
are required to match.
This differs from
.Xr grep 1 ,
where at least one pattern needs to match.
But this can also be expressed as
.Pp
.D1 Fl EG Li ' Ns Ao Ar pattern1 Ac Ns Li | Ns Ao Ar pattern1 Ac Ns Li ' .
.Pp
For example
.Pp
.Dl @vddiff@ \-rF '\(rs.[1-9]$' \-IG '^\.Dd' \-EG '/(usr|etc|var)'
.Pp
finds all manpage source files in
.Fl mdoc
format which contain absolut path names.
Options
.Fl E , e , I ,
and
.Fl i
can be used again before each
.Fl G
option to specify the kind of regular expression
and the case sensitivity for the
.Ar pattern .
Further patterns can be added with the
.Dq Li :grep Ar pattern
command,
all patterns can be removed with the
.Dq Li :nogrep
command.
.It Fl g
Use
.Dq Li gvim -dR
as diff tool and
.Dq Li gvim -R
as view tool.
.
.It Fl H Ar n
.Dq Fl H Li 1 :
Ignore missing files on left side,
.Dq Fl H Li 2 :
Ignore missing files on right side.
.
.It Fl h
Hide different files.
.It Fl I
Use case-sensitive pattern match.
.It Fl i
Use case-insensitive pattern match.
.It Fl J
Open bmode with file argument under cursor.
Exactly one argument must be given.
Intended for use by other tools only.
.It Fl K Ar fkey_number
Open bmode with file argument under cursor
and apply function key command
.Ar fkey_number .
Exactly one argument must be given.
Intended for use by other tools only.
.It Fl k
Use
.Nm tkdiff
as diff tool.
.It Fl L
Don't follow symbolic links on the command line.
.It Fl l
Follow symbolic links.
.It Fl M
Normally flags
.Fl W
and
.Fl X
are only applied on single files operations.
.Fl M
allows to use them on multiple files too.
Also skips confirmation for multiple file operations which don't
require confirmation for single file operations.
.It Fl m
Normally directories are displayed on top.
This is disabled with this option.
.
.It Fl N
When using the
.Sq Li s
(run shell) commands one may forget
that @vddiff@ is already running
and starts a new instance instead of typing
.Li ^D
to return to @vddiff@.
The tool checks this case and prevents a second invocation.
Using
.Fl N
this check is skipped.
.
.It Fl n
Hide equal files.
.It Fl O
Don't overwrite existing files.
Intented for use with
.Fl A .
.It Fl o
Hide files which are on one side only.
.
.It Fl P Ar last wd file
Write the last working directory to the specified file.
With the appropriate scripts (not yet installed with this software),
this can be used to change the shell working directory to the
last directory used in fmode or bmode.
(See
.Xr mc 1 ) .
.
.It Fl p
With options
.Fl A , D , q ,
and
.Fl T :
Print message for each processed file.
.
.It Fl Q
With options
.Fl A , D , q ,
and
.Fl T :
Exit tool on first error or difference found.
.
.It Fl q Ar file_or_directory_1 Ar file_or_directory_2
Print differing files and exit (similar to
.Dq Li diff \-q ,
but output is unsorted).
Requires two arguments.
Does not scan directories recursively until option
.Fl r
is used or RC command
.Dq Li recursive
is set.
Exit status is 0 if inputs are equal, 1 if different, 2 on error.
.It Fl R
Read-only mode:
All file change operations
(change name, permissions, owner, group; copy, move, delete)
and function keys are disabled.
To enable write mode, input
.Dq Li ":e"
or
.Dq Li ":edit" .
To only enable function keys, input
.Dq Li ":set fkeys" .
.It Fl r
Recursively scan directories to detect differences in subdirectories.
This allows to mark directories which contain differences.
It increases the start time (due to disk I/O) since
the full file tree is compared at begin.
To only show different directories this option needs to be
combined with
.Fl c .
Pressing key
.Sq c
enables to view all files in this mode.
.
.It Fl S
With options
.Fl F
and
.Fl G :
Run tool in shell mode.
With option
.Fl p
a matching line is printed too.
.
.It Fl s
With options
.Fl A , D , q , T :
Output summary how many files and bytes have been successfully processed.
Zero sized files are not counted for
.Fl A , T
and
.Fl q .
.
.It Fl T Oo Fl psW Oc Ar source_file_or_directory Ar ... Ar destination_file_or_directory
Recursively move source arguments to destination argument.
. Bl -tag
. It Fl p
Be verbose.
. It Fl s
Print summary.
. It Fl W
Force overwrite (don't ask).
. El
.
.It Fl t Ar diff_tool
Specify diff tool on the command line.
The filenames to compare are appended to the given string.
To include them into the string the symbolic names
.Dq Li $1
and
.Dq Li $2
can be used (in any order), where
.Dq Li $1
refers to the first and
.Dq Li $2
to the second file.
Note that the shell may require quoting as in
.Pp
.Dl \-t \(dqdiff \(rs$1 \(rs$2 | vim \-R \-\(dq
.It Fl U
Overwrite files only if they are older than the source file.
Intented for use with
.Fl A .
.
.It Fl V
Print version and exit.
.It Fl v Ar view_tool
Specify view tool on the command line.
The filename is appended to the given string.
To include it into the string the symbolic name
.Dq Li $1
can be embedded which is expanded to the filename.
.It Fl W
Don't ask for confirmation on file system operations.
.It Fl w
Don't start tools in background mode.
This can be useful when a tool is configured with
.Pp
.Dl ext bg
.Pp
and another tool is using
.Nm
as a general file viewer with e.g.
.Pp
.D1 Li xterm -e vddiff Ar path_name .
.Pp
In this case the external tool would be terminated
when xterm terminates.
.Pp
.D1 Li xterm -e vddiff \-w Ar path_name .
.Pp
avoids this.
.It Fl X
Don't ask for confirmation on execute.
.It Fl x Ar pattern Op Fl EeIirS
Display only directory names which match
.Ar pattern .
.It Fl Y
Non-interactive mode.
Assumes answer
.Dq no
on any question.
.It Fl y
Start in two-column mode.
This is currently only supported if two arguments are given.
.El
.Sh INTERACTIVE COMMANDS
.Bl -tag -width 12n
.It So Li Q Sc , Do Li qy Dc , Do Li :q Dc , Do Li :qa Dc
Quit
.Nm .
.It Sq Li h
When
.Cm vi_cursor_keys
is active: emulate
.Aq Cm LEFT ,
else display help.
.It Sq Li \&?
Display help.
In help mode the following inputs are valid:

.Bl -tag -width 12n

. It So Li q Sc , Aq Cm LEFT
Leave help mode.

. It Sq Q
Quit vddiff.

. It So Li + Sc , So Li j Sc , Aq Cm DOWN
Scroll down.

. It So Li - Sc , So Li k Sc , Aq Cm UP
Scroll up.

. It Mouse scroll wheel
Scroll list.

. It Ao Cm SPACE Ac , Aq Cm PAGE-DOWN
Scroll one screen down.

. It Ao Cm BACKSPACE Ac , Aq Cm PAGE-UP
Scroll one screen up.

. It Aq Cm CTRL-l
Redraw screen.

.El

.It Aq Cm CTRL-l
Refresh display.
This may be necessary after another application
had output text into the curses controlled display.
.It Aq Cm TAB
In
.Sy fmode :
Toggle column.

.It Ao Cm UP Ac , So Li k Sc or Sq Li \-
Move cursor line up.

.It Ao Cm DOWN Ac , So Li j Sc or Sq Li +
Move cursor line down.

.It Aq Cm LEFT
Leave directory (one directory up).

.It Ao Cm RIGHT Ac , Ao Cm ENTER Ac , or double click
View file, enter directory or start diff tool.
Compressed files and directories
are unpacked before the view or diff tool is started.
.Pp
If in diff mode a directory is only in one file tree,
.Aq Cm ENTER
(not
.Aq Cm RIGHT
or double click)
starts a diff between this directory and the current path
of the other file tree.
This is useful if a directory should be compared to an
archive of that directory.
Unpacking the archive creates an additional hierarchie
level which can be compensated by entering the directory
inside the archive.
.Pp
If a file is marked (with
.Sq Li m ) ,
only
.Ao Cm RIGHT Ac and double click
can be used to normally view files or enter directories.
.Aq Cm ENTER
starts a diff between the marked file
and the selected file or directory.

.It Ao Cm PAGE-UP Ac or Aq Cm BACKSPACE
Scroll one screen up.

.It Ao Cm PAGE-DOWN Ac or Aq Cm SPACE
Scroll one screen down.

.It Aq Cm CTRL-e
Scroll one line down.

.It Aq Cm CTRL-y
Scroll one line up.

.It Aq Cm CTRL-d
Scroll half screen down.

.It Aq Cm CTRL-u
Scroll half screen up.

.It Ao Cm HOME Ac or Do Li 1G Dc or Dq Li gg
Go to first file.

.It Ao Cm END Ac or Sq Li G
Go to last file.

.It Ar n Ns Sq Li G
Go to line
.Ar n .

.It So Li | Sc Ns Aq Cm LEFT
In two-column mode:
Enlarge right column by 10 characters.
.It So Li | Sc Ns Aq Cm RIGHT
In two-column mode:
Enlarge left column by 10 characters.
.It Dq Li |=
In two-column mode:
Make column widths equal.
.It Aq Cm CTRL-w
Toggle two-column mode.
.It Sq Li /
Search file in list by typing the begin of the filename.
Searching is normally done case-insensitive.
Set option
.Cm noic
to change this.
Search mode is left when a file is selected (with
.Aq Cm RIGHT
or
.Aq Cm ENTER ) .
.It Dq Li //
Search with a basic regular expression for a filename.
This can be configured with options
.Cm noic
(don't ignore case),
.Cm magic
(use extended regular expressions), and
.Cm nows
(don't wrap around when search hits top or bottom
of the file list).
Regex search mode is not left until
.Sq Li r
is pressed.
.Pp
Previously entered search patterns are saved in a history,
which can be accessed with the
.Aq Cm UP
and
.Aq Cm DOWN
keys.
.
.It Dq Li \&Sd
Sort files with directories on top.
(See also rc file option
.Cm sortic
and ex command
.Cm set sortic . )
.
.It Dq Li \&Sl
Sort files by symbolic link target.
Symbolic links are displayed first.
.
.It Dq Li \&Sm
Sort files by name only (ignoring file type).
(See also rc file option
.Cm sortic
and ex command
.Cm set sortic . )
.
.It Dq Li \&SS
Sort files by size with directories on top,
smallest file first.
.
.It Dq Li \&St
Sort files by modification time only,
oldest first (ignoring file type).
.
.It Dq Li \&Su
Sort files by owner name.
.
.It Dq Li \&Sg
Sort files by group name.
.
.It Dq Li \&SX
Sort files by name extension.
Currently does also sort directory names by extension.
This may change in future revisions.
Files are listed after directories.
.
.It Sq Li H
Put cursor to top line.
.It Sq Li M
Put cursor on middle line.
.It Sq Li L
Put cursor on bottom line.
.It Dq Li z Ns Aq Cm ENTER
Put selected file to top.
.It Dq Li z.
Center selected file.
.It Dq Li z-
Put selected file to bottom.
.It So Li ! Sc or Sq Li n
Toggle display of equal files.
.It Sq Li *
Toggle display of different files.
.It Sq Li c
Toggle display of all files or
only directories which exist in both trees
and really different files.
If option
.Fl r
is used only those directories are shown
which contain differences.
.It Sq Li &
Toggle display of files which are on one side only.
.It Dq Li &l
Hide files which are on left side only.
.It Dq Li &r
Hide files which are on right side only.
.It Sq Li ^
Toggle display of files which are in both trees.
.It Sq Li F
Toggle following symbolic links.
.It Sq Li E
Toggle file name
.Pq Fl F
or file content
.Pq Fl G
filter.
.
.It Sq Li \&,
Toggle display of hidden files.
.
.It Dq Li \&Ah
Add scaled file size column.
Does not show device major and minor numbers
to keep the column narrow.
Use
.Dq Li \&As
to display these numbers.
Removes an existing byte size column.
Can be enabled permanently with .@vddiff@rc option
.Cm disp_hsize .
.It Dq Li \&Ag
Add file group column.
Can be enabled permanently with .@vddiff@rc option
.Cm disp_group .
.
.It Dq Li \&An
Add nanosecond precision mtime column.
.
.It Dq Li \&Ap
Add file permissions column.
Can be enabled permanently with .@vddiff@rc option
.Cm disp_perms .
.It Dq Li \&As
Add file size column.
Does show device major and minor numbers
(in contrast to
.Dq Li \&Ah ) .
Removes an existing scaled size column.
.It Dq Li \&At
Add file modification time column.
Can be enabled permanently with .@vddiff@rc option
.Cm disp_mtime .
.It Dq Li \&Au
Add file owner column.
Can be enabled permanently with .@vddiff@rc option
.Cm disp_owner .
.It Dq Li \&Aa
Add file mode, owner, group, size, and modification time column.
.It Dq Li \&Rh
Remove scaled file size column.
.It Dq Li \&Rg
Remove file group column.
.
.It Dq Li \&Rn
Remove nanosecond precision mtime column.
.
.It Dq Li \&Rp
Remove file permissions column.
.It Dq Li \&Rs
Remove file size column.
.It Dq Li \&Rt
Remove file modification time column.
.It Dq Li \&Ru
Remove file owner column.
.It Dq Li \&Ra
Remove file mode, owner, group, size, and modification time column.
.It Sq Li p
Show current relative work directory.
.It Sq Li a
Show command line directory arguments.
.It Sq Li f
Show full path.
.
.It Ar n Ns Sq Li f
Select alternate function key set.
.Ar n
must be between 1 and 9.
.
.It Oo Ar n Oc Ns Dq Li <<
Copy from second to first tree.
If
.Ar n
is given,
.Ar n
files starting from the current selection are copied.
.Pp
.de Macro1
If symbolic links in source and target are followed
or not is toggled with
.Sq Li F .
..
.Macro1
Following links is signaled with letter F
on the right side of the status line.
Asks for a name for the copy
if source and destination directory are the same.
.It Oo Ar n Oc Ns Dq Li >>
Copy from first to second tree.
.Macro1
.It Dq Li \(aq<<
Copy all files between the cursor and the local mark (inclusive)
from second to first tree.
After any
.Sq Li \(aq
command the cursor is set to the mark position
if it had been below the mark.
.Macro1
.It Dq Li \(aq>>
Copy all files between the cursor and the local mark (inclusive)
from first to second tree.
.Macro1
.
.It Oo Ar n Oc Ns Sq Li C
Copy to other side.
.Macro1
.
.It Dq Li \(aqC
Copy all files between the cursor and the local mark (inclusive)
to other side.
.Macro1
.
.It Oo Ar n Oc Ns Sq Li B
Copy non-recursively to other side
(directories are created but left empty).
.Macro1
.
.It Dq Li \(aqB
Copy non-recursively all files between the cursor and the local mark (inclusive)
to other side.
.Macro1
.
.It Oo Ar n Oc Ns Sq Li U
Update files:
Overwrite older files.
Files with equal modification time and directories are ignored.
.It Dq Li \(aqU
Update all files between the cursor and the local mark (inclusive).
.It Oo Ar n Oc Ns Sq Li X
Diff mode only:
Exchange files of first and second file tree.
Only files marked with differences are exchanged.
For directories this requires recursive mode (e.g. set with option
.Fl r ) .
.It Dq Li \(aqX
Diff mode only:
Exchange all files between the cursor and the local mark (inclusive).
.It Oo Ar n Oc Ns Dq Li dd
Delete file or directory.
Does not follow symbolic links.
.Nm
does not warn if a directory to delete is not empty.
If
.Ar n
is given,
.Ar n
files starting from the current selection are deleted.
Key
.Aq Cm DELETE
can be used instead of the key sequence
.Dq Li dd .
.It Oo Ar n Oc Ns Dq Li dl
Delete file or directory in first tree.
(Does not follow symbolic links.)
.It Oo Ar n Oc Ns Dq Li dr
Delete file or directory in second tree.
(Does not follow symbolic links.)
.It Dq Li \(aqdd
Delete all files between the cursor and the local mark (inclusive).
Does not follow symbolic links.
.It Dq Li \(aqdl
Delete all files between the cursor and the local mark (inclusive)
in first tree.
(Does not follow symbolic links.)
.It Dq Li \(aqdr
Delete all files between the cursor and the local mark (inclusive)
in second tree.
(Does not follow symbolic links.)
.It Oo Ar n Oc Ns Sq Li T
Move file or directory to the other file tree.
Does a rename if source and destination directory are the same.
If used in diff mode it is tested if there is any selected file which
can be moved automatically (does exist on one side only).
When there is no such file the tool waits until
.Sq Li l
or
.Sq Li r
is pressed.
.It Oo Ar n Oc Ns Dq Li Tl
Diff mode:
Move file or directory to left file tree.
.It Oo Ar n Oc Ns Dq Li Tr
Diff mode:
Move file or directory to right file tree.
.It Dq Li \(aqT
Move all files between the cursor and the local mark (inclusive)
to the other file tree.
.It Dq Li \(aqTl
Diff mode:
Move all files between the cursor and the local mark (inclusive)
to left file tree.
.It Dq Li \(aqTr
Diff mode:
Move all files between the cursor and the local mark (inclusive)
to right file tree.
.It Oo Ar n Oc Ns Sq Li @
Create symbolic link in other column
to selected file in active column.
Asks for a name for the link
if source and destination directory are the same.
If used in diff mode it is tested if there is any selected file which
does exist on one side only.
When there is no such file the tool waits until
.Sq Li l
or
.Sq Li r
is pressed.
.It Oo Ar n Oc Ns Dq Li @l
Diff mode:
Create symbolic link in left file tree
to file in right file tree.
.It Oo Ar n Oc Ns Dq Li @r
Diff mode:
Create symbolic link in right file tree
to file in left file tree.
.It Dq Li \(aq@
Create symlinks in other column
to all files between the cursor and the local mark (inclusive)
in active column.
.It Dq Li \(aq@l
Diff mode:
Create symlinks in left file tree
to all files between the cursor and the local mark (inclusive)
in right file tree.
.It Dq Li \(aq@r
Diff mode:
Create symlinks in right file tree
to all files between the cursor and the local mark (inclusive)
in left file tree.
.It Sq Li J
Append file to marked file.
The mark must be a single file mark set with
.Sq Li m .
The files must be regular files.
Not supported in diff mode.
.It Dq Li en
Rename file.
.It Dq Li eln
Rename file in first tree.
.It Dq Li ern
Rename file in second tree.
.It Oo Ar n Oc Ns Dq Li ep
Change permissions of file.
If following symbolic links is not enabled
the command is ignored for symbolic links.
If decimal digit
.Ar n
is given, the mode of
.Ar n
files starting from the current selection is set.
.It Oo Ar n Oc Ns Dq Li elp
Change permissions of file in first tree.
.It Oo Ar n Oc Ns Dq Li erp
Change permissions of file in second tree.
.It Dq Li \(aqep
Change permissions of
all files between the cursor and the local mark (inclusive).
.It Dq Li \(aqelp
Change permissions of
all files between the cursor and the local mark (inclusive)
in first tree.
.It Dq Li \(aqerp
Change permissions of
all files between the cursor and the local mark (inclusive)
in second tree.
.It Oo Ar n Oc Ns Dq Li eu
Change owner of file.
If following symbolic links is not enabled
the command is ignored for symbolic links.
Previously entered user names are saved in a history,
which can be accessed with the
.Aq Cm UP
and
.Aq Cm DOWN
keys.
If decimal digit
.Ar n
is given, the owner of
.Ar n
files starting from the current selection is set.
.It Oo Ar n Oc Ns Dq Li elu
Change owner of file in first tree.
.It Oo Ar n Oc Ns Dq Li eru
Change owner of file in second tree.
.It Dq Li \(aqeu
Change owner of
all files between the cursor and the local mark (inclusive).
.It Dq Li \(aqelu
Change owner of
all files between the cursor and the local mark (inclusive)
in first tree.
.It Dq Li \(aqeru
Change owner of
all files between the cursor and the local mark (inclusive),
in second tree.
.It Oo Ar n Oc Ns Dq Li eg
Change group of file.
If following symbolic links is not enabled
the command is ignored for symbolic links.
Previously entered group names are saved in a history,
which can be accessed with the
.Aq Cm UP
and
.Aq Cm DOWN
keys.
If decimal digit
.Ar n
is given, the group of
.Ar n
files starting from the current selection is set.
.It Oo Ar n Oc Ns Dq Li elg
Change group of file in first tree.
.It Oo Ar n Oc Ns Dq Li erg
Change group of file in second tree.
.It Dq Li \(aqeg
Change group of
all files between the cursor and the local mark (inclusive).
.It Dq Li \(aqelg
Change group of
all files between the cursor and the local mark (inclusive)
in first tree.
.It Dq Li \(aqerg
Change group of
all files between the cursor and the local mark (inclusive),
in second tree.
.It Sq Li P
Create directory
.Sy ( bmode
and
.Sy fmode
only).
.It Dq Li Pl
Create directory in left tree.
.It Dq Li Pr
Create directory in right tree.
.It Sq Li \&.
Repeat last file system or function key command.
For commands using marks and the
.Sq Li \(aq
key the number of files is saved.
This number is applied on a
.Sq Li \&.
command, starting from the cursor position
(the mark is not relevant then).
.It Sq Li m
Mark file or directory.
This can be used to compare files or directories
which had been renamed or compressed in one file tree.
.Pp
Marks are defined globally and can be used to compare
files from different file hierarchy depths.
They can only be undefined with the
.Sq Li r
key (or redefined with the
.Sq Li m
key).
As long as the current directory is not left,
the marked file is highlighted with either a bold font
or a blue background.
(In
.Sy fmode
marks are cleared if the directory is left
or if any external command is executed.)
.Pp
If a mark is set, only
.Aq Cm RIGHT
and double click
can be used to normally view files or change to other directories.
.Aq Cm ENTER
startes a diff between the marked and the selected file
or directory.
.It So Li V Sc , Ao Cm INSERT Ac , mouse button 3
Set multiple marks.
If no local mark is set (using
.Sq Li m ) ,
.Sq Li V
toggles the mark of the current line
and moves the cursor to the next line.
If a local mark is set,
the marks of all lines from the line with the local mark
to the current line are inverted.
Unless other marks multiple marks are removed with
.Sq Li u
instead of
.Sq Li r .
(Multiple marks are not automatically removed after a
file copy operation to allow removing the copied files.)
.It Dq Li VG
Toggle mark of all files from the cursor position
to the last line.
.It Dq Li 1GVG
Toggle mark of all files.
(vim uses
.Dq Li gg
instead of
.Dq Li 1G ,
but this is not a traditional vi command.)
.It Sq Li r
Remove mark, edit line, or regex search.
Does not remove multiple marks, use
.Sq Li u
instead.
.
.It Sq Li b
Test for binary difference between selected and marked file.
Compressed files are unpacked but compressed archive files
are compared directly.
.
.It Sq Li Z
Test for binary difference between selected and marked file.
Compressed files are not unpacked.
.
.It Sq Li y
Copy file path(s) to edit line.
If a
.Sq Li $
command is entered later, this file path can be used
to build a
.Xr sh 1
command.
.Pp
To use multiple paths in bmode or fmode
.Sq Li y
can be used multiple times before pressing
.Sq Li $ .
.
.It Sq Li Y
Copy file paths to edit line in reverse order.
.
.It Sq Li $
Enter shell command.
If paths had been copied to the edit line before using the
.Sq Li y
or
.Sq Li Y
command, the shell command can be prepended by pressing
.Aq Cm HOME
and then entering the command.
Predefined strings can be inserted by pressing a
function key.
The work directory is the directory where
.Nm
had been started.
(In
.Sy bmode
and
.Sy fmode
the work directory is always the current view directory.)
Each entered command is saved in a history.
The keys
.Aq Cm UP
and
.Aq Cm DOWN
fetch other history entries.
The shell to be used (default
.Dq Li sh )
can be configured with the
.Sy sh
option.
.It Oo Ar n Ns Li | Ns Cm \(aq Oc Ns Ao Cm F1 Ac \(en Aq Cm F48
Define string which can be inserted later with this function key
when entering a
.Xr sh
command using
.Sq Li $ .
This string is usually the name of a UNIX tool.
Regularly used strings can be set using the RC file
.Cm fkey
command.
.Pp
If the string begins with a
.Sq Li $
followed by at least one space
.Pq Sq Li " "
it is treated as shell command itself, which is
applied to a selected file(s).
If that function key is pressed later, a dialog opens
to ask if the command should be executed or the function
key should be redefined.
The filename is appended to the saved string.
To embed it,
.Dq Li $1
and
.Dq Li $2
can be used, as in
.Dq Li "$ nroff $1 | less" .
If the filename contains spaces or shell meta characters
escapes are inserted automatically.
.Pp
If
.Ar n
is given,
the command is applied to
.Ar n
files starting from the current selection.
If
.Sq Li \(aq
is prepended instead, the command is applied to
all files between the cursor and the local mark (inclusive).
.Pp
If the string starts with
.Sq Li \&!
or
.Sq Li %
instead of
.Sq Li $ ,
.Aq Cm ENTER
must be pressed after running the command.
This allows to check the command's output.
.Pp
For strings starting with
.Sq Li $
or
.Sq Li \&!
the user has to confirm the command execution.
(If it starts with
.Sq Li #
or
.Sq Li %
instead, the command is started immediately.)
.Pp
Summary:
.Bl -column -offset indent ".Sq Li %"
.It So Li $   Sc Ta Confirm command execution (e.g. for dangerous commands with no diagnostic output)
.It So Li #   Sc Ta Just run command (e.g. for GUI tools)
.It So Li \&! Sc Ta Confirm command execution and check output
.It So Li %   Sc Ta Start command immediately but check output
.It So Li >   Sc Ta Start command immediately and open shell in current directory
.El
.Pp
To save a command for a function key which does not take
the selected filename as argument, add a space followed
by an octothorpe
.Pq Dq Li " #"
at the end of the string.
.Pp
If no diff tool which supports merging is available,
files can be merged manually by defining two function keys
for editing the left and right side file with
.Dq Li "$ vi $1"
and
.Dq Li "$ vi $2" .
.It Sq Li l
When
.Cm vi_cursor_keys
is active: emulate
.Aq Cm RIGHT ,
else list strings which had been defined for a function key.

.It Sq Li K
List strings which had been defined for a function key.

.Bl -tag -width 12n

. It Ao Cm UP Ac , So Li k Sc , So Li \- Sc , Ao Cm CTRL-y Ac
Scroll one line down.

. It Ao Cm DOWN Ac , So Li j Sc , So Li + Sc , Ao Cm CTRL-e Ac , Aq Cm ENTER
Scroll one line up.

. It Ao Cm LEFT Ac , Sq h
Select previous f-key set.

. It Ao Cm RIGHT Ac , Sq l
Select next f-key set.

. It So 0 Sc ... Sq 9
Select f-key set 0 ... 9.

. It Ao Cm PAGE-UP Ac or Aq Cm BACKSPACE
Scroll one screen down.

. It Ao Cm PAGE-DOWN Ac or Aq Cm SPACE
Scroll one screen up.

.\". It Aq Cm CTRL-d
.\"Scroll half screen up.
.\"
.\". It Aq Cm CTRL-u
.\"Scroll half screen down.
.\"
.\". It Ao Cm HOME Ac
.\"Go to first line.
.\"
.\". It Ao Cm END Ac
.\"Go to last line.

. It Ao Cm F1 Ac ... Aq Cm F48
Activate f-key function
. Cm F1
\&...\&
. Cm F48 .

. It Sq q
Leave view.

. It Sq Q
Quit vddiff.

.El

.It Sq Li u
Update file list.
Also used to remove multiple marks
.Sq ( Li r
can't be used to remove them).
.It Sq Li s
Open shell in the directory of the selected file.
Does not work in diff mode when both files exist
(use
.Dq Li sl
or
.Dq Li sr
instead).
The shell to open can be set with the
.Sy shell
option, else it is read from the user's entry in
.Pa /etc/passwd .
.It Dq Li sl
Open shell in left directory tree.
.It Dq Li sr
Open shell in right directory tree.
.It Sq Li o
Open file (instead of diff tool).
.It Dq Li ol
Open left file or directory.
Plain files are opened with
.Xr less 1
by default.
If no diff tool which supports merging is available,
files can be merged manually opening them with
.Dq Li ol
or
.Dq Li or
and then pressing
.Sq Li v
in
.Li less
which opens
.Li vi .
.It Dq Li or
Open right file or directory.
.It Sq Li v
View raw file contents.
.It Dq Li vl
View raw left file contents.
.It Dq Li vr
View raw right file contents.
.It Sq Li \&:
Enter command.
Arguments to the
.Dq Li :set
command can be combined (e.g.\&
.Dq Li :set loop random ) .
.Bl -tag -width 12n
.It Li \&! Ns Ar shell_command
Enter shell command.
.It Li cd
bmode and fmode only:
Change to home directory.
.It Li cd Ar path
bmode and fmode only:
Change to directory
.Ar path .
.Ar path
may be absolute or relative.
.Sq Li ~ ,
.Dq Li ~ Ns Ar user
and environment variables are expanded
but not (yet) auto-completed.
Other path components are auto-completed on pressing
.Aq Cm TAB .
This does only work when the cursor is at the
end of the input string.
.It Li e Ns Op Li dit
Allow file change operations and function keys.
.It Li find Ar pattern
Display only file names which match
.Ar pattern .
.It Li find_dir Ar pattern
Display only directory names which match
.Ar pattern .
.It Li nofind
Remove file and directory name pattern.
.It Li grep Ar pattern
Display only files which contain
.Ar pattern .
.It Li nogrep
Remove file content pattern.
.It Li marks
List jump marks.
.It Li q , Li qa
Quit @vddiff@.
.It Li set all
Display the current setting of the changable options.
.It Li set file_exec
bmode and fmode only:
Enable execution of executeable files by pressing
.Aq Cm ENTER
(no mark must be set).
Double mouse click or pressing
.Aq Cm RIGHT ,
.Sq Li o ,
or
.Sq Li v
does not execute the file.
.It Li set nofile_exec
Disable execution of executeable files when
.Aq Cm ENTER
is pressed.
.It Li set fkeys
Enable function keys.
.It Li set nofkeys
Disable function keys.
.It Li set ic
Set case-insensitive match.
.It Li set noic
Set case-sensitive match.
.It Li set loop
Set loop mode.
If in this mode several files are marked and a
function key command is started, the files are
processed in a loop.
This could make sense if the command is e.g. an
audio player.
.It Li set noloop
End loop mode.
.
.It Li set magic
Use extended regular expressions.
.
.It Li set nomagic
Use basic regular expressions.
.
.It Li set preserve
Preserve file attributes on copy.
.
.It Li set nopreserve
Don't preserve file attributes on copy.
.
.It Li set random
Process multiple marked files in random order.
.It Li set norandom
End random mode.
.It Li set recursive
Use recursive diff, find and grep operations.
.It Li set norecursive
Use directory local diff, find and grep.
.It Li set sortic
Sort files case-insensitive.
.It Li set nosortic
Sort files case-sensitive.
.It Li set ws
File name searches wrap around top and bottom.
.It Li set nows
File name searches don't wrap around top and bottom.
.It Li vie Ns Op Li w
Read-only mode:
Disable file change operations and function keys.
.El
.Pp
Previously entered commands are saved in a history,
which can be accessed with the
.Aq Cm UP
and
.Aq Cm DOWN
keys.
If possible, commands and their arguments are auto-completed
on pressing
.Aq Cm TAB .
To e.g. input
.Dq Li set recursive
it is sufficient to type
.Pp
.D1 Li :s Ns Ao Cm TAB Ac Ns Li r Ns Aq Cm TAB
.It Sq Li #
Toggle between diff mode and two-column browse mode
.Sy ( fmode ) .
.It Sq Li =
In
.Sy fmode :
Set path of active column to path of the other column.
.It Sq Li %
Toggle ignoring file contents for further diff operations.
This is useful if only differences regarding the file existence
are of interest.
Any time this function is disabled,
the currently displayed directories are compared again.
.Sq Li %
can be pressed during this directory compare (short and only one time)
to abort it.
Note that an active file diff is not interrupted.
This may take some time in case of a huge file.
.It Dq Li \&Da
Add current directory to a persistent list.
Items on this list can be selected later using the
.Dq Li \&Dl
command.
.It Dq Li \&Dl
Show persistent directory list.
In this list the following inputs are valid:
.Bl -tag -width 12n
.It Sq Li Q
Quit vddiff.
.It So Li q Sc , Aq Cm LEFT
Close directory list.
.It So Li + Sc , So Li j Sc , Aq Cm DOWN
Move cursor down.
.It So Li - Sc , So Li k Sc , Aq Cm UP
Move cursor up.
.It So Li " " Sc , Aq Cm PAGE-DOWN
Scroll one page down.
.It Ao Cm BACKSPACE Ac , Aq Cm PAGE-UP
Scroll one page up.
.It Do Li 1G Dc , Aq Cm HOME
Go to first line.
.It So Li G Sc , Aq Cm END
Go to last line.
.It Ar n Ns Sq Li G
Change into directory
.Ar n .
.It Ao Cm ENTER Ac , Aq Cm RIGHT
Change into directory.
.It Do Li dd Dc , Aq Cm DELETE
Delete entry.
.It Mouse button 1
Select entry.
.It Mouse button 1 double click
Change into directory.
.It Mouse scroll wheel
Scroll list.
.It Sq Li H
Place cursor in top line.
.It Sq Li M
Place cursor in middle line.
.It Sq Li L
Place cursor in bottom line.
.It Sq Li /
Start regex search.
.It Sq Li n
Find next matching pattern.
.It Sq Li N
Find previous matching pattern.
.It Sq Li r
Finish regex search.
.It Sq Li A
Add short description for a list entry.
A description can be removed by entering an empty string.
.It Sq Li ^
Toggle between showing path plus description or description only.
.It Aq Cm CTRL-l
Rebuild screen.
.El
.It Aq Cm CTRL-g
Print cursor line number and number of files.
.It Dq Li \(aq\(aq
Jump to previous cursor position.
.It Ar n Ns Sq Li m
Set jump mark.
.Ar n
is a number between 0 and 31.
(In contrast to vi a number instead of a letter is used
and
.Sq Li m
is behind instead of before the number.)
Jump marks save the file position, not the file name.
If the position of the file in the list changes,
the mark points to an other file.
.begin_comment
The mark can't be saved in diffinfo, since all diffinfo structures
are freed on reload.
.end_comment
.It Ar n Ns Sq Li \(aq
Jump to mark
.Ar n .
.It Dq Li \(aql
List jump marks.
.It Sq Li W
Toggle to always wait for
.Aq Cm ENTER
after running an external tool.
This can be useful for debugging purposes.
.El
.
.
.
.Sh CONFIGURATION FILE ~/.@vddiff@rc
.
.
.
Permanent non-default options can be set in the file
.Pa ~/.@vddiff@rc ,
which has a very simple
.Em ( not
\&.exrc like) syntax.
The elements in this file may be separated with
spaces, tabs or line breaks.
Line breaks are not required, everything can be written
into one long line.
Also spaces or tabs are not required (outside quoted strings),
when every element is on it's own line.
Everything following a
.Sq Li #
(outside quoted strings)
to the end of the line is a comment.
.Pp
Quoted strings can be split over several lines
by placing a backslash
.Pq Sq Li \(rs
at the end of a line.
No character is allowed to follow this backslash
on the same line, not even a white space character.
All occurrences of a backslash followed by a new line
character (i.e. a line break) are removed before storing
the quoted string.
.Pp
To embed a double quote sign
.Sq ( Li \(dq )
into a quoted string, precede it with a backslash.
This backslash is removed before storing the string.
All other backslashes are preserved.
.Bl -tag -width 12n
.
.It Li vi_cursor_keys
Use
.Cm vi
cursor keys
.Cm h , j , k
and
.Cm l .
Normally h is bound to the help menu and l shows the function key bindings.
When this command is used, keys h and l are bound to
.Dq cursor left
and
.Dq cursor rigth ,
respectively.
.
.It Li twocolumn
Start in two-column mode.
This is currently only supported if two arguments are given.
.
.It Li difftool Ar string
Configure
.Ar string
as diff tool.
If
.Ar string
contains spaces it needs to be quoted with
.Sq Li \(dq
at begin and end.
The two filenames are appended to this string.
If the filenames need to be before a pipe symbol
.Pq Sq Li | ,
the symbols
.Dq Li $1
and
.Dq Li $2
can be embedded into
.Ar string
(in any order).
These symbols are expanded to the respective filename.
.Pp
Other possible diff tools are
.Xr colordiff 1 ,
.Xr mgdiff 1 ,
or
.Xr tkxcd 1 .
.It Li difftool bg Ar string
Start
.Ar string
as a background process (don't block
.Nm
while executing
.Ar string ) .
.Cm bg
is ignored if one of the files to be compared is compressed.
Since they are decompressed into a temporary directory
which is removed after starting the diff tool,
the file may be removed before the tool reads it.
.
.It Li viewtool Ar string
Configure
.Ar string
as view tool.
If
.Ar string
contains spaces it needs to be quoted with
.Sq Li \(dq
at begin and end.
The filename is appended to this string.
If the filename need to be before a pipe symbol
.Pq Sq Li |
the symbol
.Dq Li $1
can be embedded into
.Ar string ,
which is expanded to the filename.
.
.It Li viewtool bg Ar string
Start
.Ar string
as a background process.
.Cm bg
is ignored if the file to be viewed is compressed.
Since it is decompressed into a temporary directory
which is removed after starting the view tool,
the file may be removed before the tool reads it.
For example
.Pp
.Dl viewtool bg \(dqxterm -e less\(dq
.Pp
displayes every file to view in a separate window while not
blocking the file browser.
.
.It Li preserve_mtim
Preserve modification time on copying regular files.
This command had been introduced for compatibility with version 1.11
which did preserve file modification time by default.
.
.It Li preserve_all
Preserve all file attributes on copy except file type.
(Following links is selected with
.Cm followlinks . )
.
.It Li nopreserve
Don't preserve file attributes on copy.
.
.It Li override
Using
.Cm ext
twice for the same extension
or
.Cm alias
twice for the same alias
normally leads to a fatal error.
When
.Li override
is set, the previous command is redefined.
.
.It Li ext Ar extension Ar string
Configure view tool
.Ar string
for filenames ending with
.Dq Li "." Ns Ar extension .
.Ar extension
is compared case-insensitive.
If
.Ar extension
is an integer number it needs to be enclosed
in double quotes
.Pq Sq \(dq
as in
.Pp
.Dl ext \(dq1\(dq \(dqtbl $1 | neqn | nroff \-mandoc | less\(dq
.Pp
because the parser expects a string (and not a number)
after the keyword
.Li ext .
.
.It Li ext Ar extension Li bg Ar string
Start
.Ar string
as a background process.
.It Li ext Ar extension Li wait Ar string
Wait for a key pressed after starting
.Ar string
as a background process.
If
.Ar string
should be started as background process
but applied to a compressed file, the decompressed
file may be removed before
.Ar string
is started.
When using key word
.Cm wait ,
the tool waits for pressing a key before it continues
(and removes the decompressed file).
.
.It Li alias Ar name Ar string
If a pipe of tools (like the nroff pipe above)
or a command with options (like e.g.
.Dq Li mplayer \-idx \-\- )
should be applied to many file types,
an alias
.Ar name
can be defined for such a
.Ar string .
The
.Sy ext
command can then use this alias
.Ar name
instead the full command
.Ar string ,
for example
.Bd -literal -offset indent
alias mandoc  "tbl $1 | neqn | nroff -mandoc | less"
alias mplayer "mplayer -idx --"

ext "1" mandoc
ext "2" mandoc
ext "3" mandoc

ext mts mplayer
ext ts  mplayer
.Ed
.Pp
It is also possible to use an alias for defining another alias:
.Bd -literal -offset indent
alias mplayer "mplayer -idx --"
alias audio mplayer

ext mpg mplayer
ext mp3 audio
.Ed
.
.It Li alias Ar name Li bg Ar string
Start
.Ar string
as a background process.
.
.It Li alias Ar name Li wait Ar string
Wait for pressing a key after starting
.Ar string
as a background process.
.
.It Li skipext Ar extension
When checking a filename extension skip
.Ar extension
at the end of the filename.
E.g.
.Pp
.Dl skipext old
.Pp
would remove
.Dq Li .old
from the end of each filename before checking the
extension.
.
.It Li fkey Ar number Ar string Op Ar comment
Define
.Ar string
which can be inserted later with this function key
when entering a sh command using
.Sq Li $ .
This string is usually the name of a UNIX tool.
When
.Ar comment
is given, it is displayed in the list of the
.Sq Li l
command.
.Pp
.Ar number
is basically between 1 and 48 (inclusive).
To specify additinal sets of function key definitions,
a number between 2 and 9 multiplied with 100 can be added
(1 would has the same effect as 0).
For example
.Dq Li fkey 307 Ar string
would define a string for F7 in set 3.
One out of 9 sets is selected later by typing
.Ar n Ns Li f
where
.Ar n
is between 1 and 9.
.Pp
If
.Ar string
begins with a
.Sq Li $
followed by at least one space (the string needs to be
enclosed in double quotes in this case),
it defines a shell command to be executed
for the selected file
when pressing the function key.
.Pp
If
.Ar string
starts with
.Sq Li \&!
instead of
.Sq Li $ ,
.Aq Cm ENTER
must be pressed after running the command.
This allows to check the command's output.
.Pp
To save a command for a function key which does not take
the selected filename as argument, add a space followed
by an octothorpe
.Pq Dq Li " #"
at the end of the string.
.
.It Li fkey_set Ar number
Set initial function key set.
.Ar number
must be between 1 and 9.
.
.It Li sortic
Sort files case-insensitive.
.It Li mono
Disable colors.
.It Li followlinks
Follow symbolic links.
.
.It Li noequal
Display differences only, hide equal files.
.
.It Li real_diff
Show only directories which exist in both trees
and really different files.
.
.It Li recursive
Recursively scan file tree to detect and mark
directories which contain differences.
This increases the start time.
To show only directories with differences
additionally set option
.Li real_diff .
To view all files when in this mode key
.Sq c
can be used.
.
.It Li noic
Searching for a filename with
.Sq Li /
or
.Dq Li //
is normally done case-insensitive.
Case-sensitive search can be configured with this option.
.
.It Li magic
For searching with
.Dq Li //
normally basic regular expressions are used.
Use of extended regular expressions is configured
with this option.
.It Li nows
Searching for a filename with
.Dq Li //
normally wraps around top and bottom of the file list.
This behaviour is disabled with this option.
.It Li include Ar string
Include RC file
.Ar string .
If
.Ar string
does not start with
.Sq Li / ,
.Li $HOME
is prepended.
.Sq Li ~
and
environment variables are
.Em not
expanded.
(The include command does only work
if @vddiff@ had been build with a lex version
which supports buffer switching.)
.It Li uz_add Ar file_extension Ar decompress_algorithm
Assign new file extension to an implemented decompress algorithm.
Currently the following file extensions are assigned:
.Bl -column -offset indent ".Sy Extension" ".Sy Algorithm"
.It Sy Extension Ta Sy Algorithm
.It Li bz2     Ta Li bz2
.It Li gz      Ta Li gz
.It Li jar     Ta Li zip
.It Li ods     Ta Li zip
.It Li odt     Ta Li zip
.It Li pptx    Ta Li zip
.It Li rar     Ta Li rar
.It Li tar     Ta Li tar
.It Li tar.bz2 Ta Li tbz
.It Li tar.gz  Ta Li tgz
.It Li tar.xz  Ta Li txz
.It Li tar.Z   Ta Li tar.Z
.It Li tbz     Ta Li tbz
.It Li tgz     Ta Li tgz
.It Li txz     Ta Li txz
.It Li xz      Ta Li xz
.It Li Z       Ta Li gz
.It Li zip     Ta Li zip
.It Li xlsx    Ta Li zip
.El
.It Li uz_del Ar file_extension
If it is not desired to decompress a file with a file extension
listed above (or added with
.Cm uz_add ) ,
the file extension can be removed with this command.
.It Li filesfirst
Display directories at the end instead on top.
.It Li mixed
Display files and directories mixed.
.
.It Li hidden
Show hidden files.
.
.It Li nohidden
Don't show hidden files.
.
.It Li dir_color Ar integer
Set color for directories.
Default is 3 (yellow).
.It Li diff_color Ar integer
Set color for different files.
Default is 1 (red).
.It Li link_color Ar integer
Set color for symbolic links.
Default is 5 (magenta).
.It Li left_color Ar integer
Set color for files found in first directory only.
Default is 6 (cyan).
.It Li right_color Ar integer
Set color for files found in second directory only.
Default is 2 (green).
.It Li unknown_color Ar integer
Set color for unknown file types.
Default is 4 (blue).
.It Li normal_color Ar integer
Set color for normal text.
Default is 7 (white).
.
.It Li bg_color Ar integer
Set background color.
Default is 0 (black).
E.g.
.Pp
.Dl bg_color 4 mark_color 7 0
.Pp
changes the background color to blue
(and the normally blue mark color to black).
.
.It Li cursor_color Ar foreground Ar background
Set the cursor color.
.Ar foreground
and
.Ar background
must be given as integers.
Default is 0 7 (black on white).
.
.It Li mark_color Ar foreground Ar background
Set color for marks.
.Ar foreground
and
.Ar background
must be given as integers.
Default is 7 4 (white on blue).
.
.It Li mmrk_color Ar foreground Ar background
Set color for multiple marks.
.Ar foreground
and
.Ar background
must be given as integers.
Default is 0 3 (black on yellow).
.
.It Li error_color Ar foreground Ar background
Set color for diff errors.
.Ar foreground
and
.Ar background
must be given as integers.
Default is 7 1 (white on red).
.
.It nobold
Don't use bold font for colored text.
.
.It Li histsize Ar integer
Set history size to
.Ar integer .
Default is 100.
A size less than 2 disables the history
(at least the current command line and one previous
entry need to be saved to use this feature).
.
.It Li scale
Show file size in human-readable format.
.
.It Li disp_all
Add columns for file permissions,
file owner,
file group,
scaled file size, and
file modification time.
.
.It Li disp_perms
Add file permissions column.
Can be removed with
.Dq Li \&Rp
.
.It Li nodisp_perms
Remove file permissions column.
.
.It Li disp_owner
Add file owner column.
Can be removed with
.Dq Li \&Ru
.
.It Li nodisp_owner
Remove file owner column.
.
.It Li disp_group
Add file group column.
Can be removed with
.Dq Li \&Rg
.
.It Li nodisp_group
Remove file group column.
.
.It Li disp_hsize
Add scaled file size column.
Does not show device major and minor numbers
to keep the column narrow.
Use
.Dq Li \&As
to display these numbers.
Can be removed with
.Dq Li \&Rh
.
.It Li nodisp_hsize
Remove file size column.
.
.It Li disp_mtime
Add file modification time column.
Can be removed with
.Dq Li \&Rt
.
.It Li nodisp_mtime
Remove modification time column.
.
.It Li file_exec
bmode and fmode only:
Enable execution of executeable files by pressing
.Aq Cm ENTER
(no mark must be set).
Double mouse click or pressing
.Aq Cm RIGHT ,
.Sq Li o ,
or
.Sq Li v
does not execute the file.
.It Li shell Ar string
Set shell for the
.Sq Li s ,
.Dq Li sl
and
.Dq Li sr
command.
Default is the user's login shell.
.Ar string
may be a full path or just the shell name.
In the latter case
.Li $PATH
is searched to determine the full path.
.Pp
Since
.Li sh
is a keyword it would need to be enclosed with quotes
to use it as an argument,
else a syntax error is reported.
.Ar string
can have arguments (like
.Li \(dqbash -l\(dq )
to e.g. start a login shell.
.It Li sh Ar string
Set shell for the
.Sq Li $
and function key commands,
.Li .gz
and
.Xr .bz2
uncompressing
and any use of the shell special characters
.Li | , & , \&; , < , > , \&( , \&) , \(ga , \(rs , \(dq , \(aq , \&[ , # ,
and
.Li ~ .
Default is
.Dq Li sh .
.Ar string
may be a full path or just the shell name.
In the latter case
.Li $PATH
is searched to determine the full path.
.It Li readonly
Read-only mode:
All file change operations
(change name, permissions, owner, group; copy, move, delete)
and function keys are disabled.
Function keys get enabled if a
.Cm fkey
keyword is read after
.Cm readonly .
To avoid this,
.Cm readonly
can be placed at the end of the RC file.
.begin_comment
.It Li locale Ar locale_name
Set locale
.Ar locale_name .
.end_comment
.
.It Li dotdot
Browse mode only:
Show directory entry
.Dq Li .. .
.
.It Li nodotdot
Browse mode only:
Don't show directory entry
.Dq Li .. .
.
.El
.
.
.
.Sh VDDIFF MODES
.
.
.
.Nm
has four modes:
A diff mode and a browser mode, both have an
one-column and a two-column submode.
The following table shows the transition
bewteen these modes:
Key
.Aq Cm CTRL-w
toggles between one-column and two-column mode
and key
.Sq Li #
toggles between diff mode and browse mode:
.Bd -literal -offset indent
.if t .ne 11
               [1-column]        [2-column]

[Diff mode]          <---- \(oq^W\(cq ---->
                   ^                  ^
                   |                  |

                  \(oq#\(cq                \(oq#\(cq

                   |                  |
                   v                  v
[Browse mode]        <---- \(oq^W\(cq ---->
.Ed
.Pp
While the diff modes access files with their path name,
the browse modes always set the current working directory
to the active file list column.
This is relevant if shell commands are applied
which create files.
Marks are cleared on any mode change except switching
between one-column and two-column diff mode.
.Ss "One-column diff mode"
Diff mode is entered when two arguments are used.
Key
.Aq Cm CTRL-w
switches to two-column diff mode,
key
.Sq Li #
switches to two-column browse mode.
.Ss "Two-column diff mode"
Two-column diff mode is equal to diff mode
except for a different data presentation.
Key
.Aq Cm CTRL-w
switches to single-column diff mode,
key
.Sq Li #
switches to two-column browse mode.
.Ss "One-column browse mode (bmode)"
Bmode is a simply file browser mode.
It allows file and directory comparison by use of marks.
.begin_comment
Since bmode uses chdir instead of paths
it needs to resolve paths with symbolic links.
.end_comment
Key
.Aq Cm CTRL-w
switches to two-column browse mode.
.Ss "Two-column browse mode (fmode)"
Fmode is a simple two-column file manager mode.
It allows comparison of files and directories
by use of local marks.
This mode does not have global marks.
If a directory is left, an existing mark in this
directory is deleted.
Generally in any mode at most one mark is supported
(except the multi-marks set with
.Sq Li V ) .
If a mark is defined, an existing mark (in either column)
is deleted.
.Pp
The symbolic variables
.Dq Cm $1
and
.Dq Cm $2
exchange when the cursor is in the right column.
That means
.Dq Cm $1
is the file from the cursor column and
.Dq Cm $2
is the marked file in the other column.
.Pp
Key
.Aq Cm CTRL-w
switches to single-column browse mode,
key
.Sq Li #
or a compare of a marked directory (or archive)
with a directory (or archive)
switches to two-column diff mode.
.
.
.
.Sh MOUSE SUPPORT
.
.
.
For mouse support currently the ncurses interface is used
which means that ncurses is required if one wants to use the mouse.
Furthermore at least ncurses version 6 is currently required
for using the mouse scroll wheel.
.Pp
If the middle bar can be moved with the mouse to resize the
columns in two-column mode is terminal dependend.
See section
.Sx PORTABILITY
in
.Xr mouse 3ncurses .
For example, to make this function best work in
.Xr xterm ,
set
.Dq Li TERM=xterm-1002
(else usually a further mouse click is required to finalize
the resize).
.
.
.
.Sh FILES
.
.
.
.Bl -tag -width ~/.@vddiff@info
.
.It Pa /etc/@vddiff@/@vddiff@rc
Read on start-up to set non-default options.
.
.It Pa /etc/@vddiff@rc
If
.Pa /etc/@vddiff@/@vddiff@rc
does not exist
.Pa /etc/@vddiff@rc
is read instead.
.
.It Pa ~/.@vddiff@rc
If
.Pa ~/.@vddiff@rc
does exist, it is read instead of
.Pa /etc/@vddiff@/@vddiff@rc .
To read both, add an
.Cm include
statement into
.Pa ~/.@vddiff@rc .
.
.It Pa ~/.@vddiff@info
Storage for persistant information.
.
.El
.
.
.
.Sh EXIT STATUS
.
.
.
For
.Nm Fl A ,
.Nm Fl D ,
and
.Nm Fl T
the exit status is 0 on success and
2 on error.
.
.Pp
.
For
.Nm Fl F ,
.Nm Fl G ,
and
.Nm Fl x
the exit status is 0 for a pattern match,
1 if there was no match, and
2 if an error occurred.
.
.Pp
.
For
.Nm Fl q
the exit status is 0 if no difference had been found,
1 for a difference, and
2 on error.
.
.
.
.Sh EXAMPLES
.
.
.
To display only differing files and subdirectories which contain
differing files in two-column mode enter
.Pp
.D1 Li @vddiff@ -cry Ar directory_1 directory_2
.Pp
where
.Fl c
hides equal files, files which exist in one directory only and directories
which don't contain differing files.
Pressing
.Sq Li c
toggles showing all files.
.Fl r
enables recursive mode.
This option increases the start time,
if huge directories are compared.
If this takes too long,
.Sq Li %
can be pressed to disable further file content comparison.
.Fl y
enables two-column mode.
.Pp
To only hide equal files enter
.Pp
.D1 Li @vddiff@ -nry Ar directory_1 directory_2
.Pp
Pressing
.Sq Li n
toggles showing all files.
.Pp
If a recursive diff is not required,
.Pp
.D1 Li @vddiff@ -y Ar directory_1 directory_2
.Pp
(optionally with option
.Fl c
or
.Fl n )
is much faster,
since a diff is only done,
when a directory is entered.
The only disadvantage is,
that also directories may be shown,
which contain no differences
(since the tool had not visited them yet).
.Pp
The arguments of @vddiff@ need not be directories.
If
.Pa ~/.@vddiff@rc
is setup accordingly,
.Pp
.D1 Li @vddiff@ Ar file Ns Li .1.gz
.Pp
opens a manual page,
.Pp
.D1 Li @vddiff@ Ar file Ns Li .mpg
.Pp
plays a movie, etc.
Compressed files are unpacked automatically.
.Pp
.D1 Li @vddiff@ Ar file_1 file_2
.Pp
starts
.Nm vimdiff .
Again, any argument may be a compressed file.
.Pp
.D1 Li @vddiff@ Ar file Ns Li .tgz
.Pp
opens an archive,
.Pp
.D1 Li @vddiff@ Ar file_1 Ns Li .tgz Ar file_2 Ns Li .zip
.Pp
compares two archives and
.Pp
.D1 Li @vddiff@ Ar file Ns Li .txz Ar directory
.Pp
compares an archive with a directory.
.
.begin_comment
.Pp
.D1 Li @vddiff@ -u -AOps Ar source_path Ar target_path
.Pp
Recursively copy new files from
.Ar source_path
to
.Ar target_path ,
print progress and summery.
.end_comment
.
.
.
.Sh SEE ALSO
.
.
.
.Bl -tag -width 8n
.It Lk http://n-t-roff.github.io/vddiff/vddiff.1.pdf
This manual page as a PDF document with hyperlinks.
.It Lk http://n-t-roff.github.io/vddiff/vddiff.1.html
This manual page as a HTML document with hyperlinks.
.El