   GIT: A set of interactive tools, by Tudor Hulubei and Andrei Pitis.

   This file documents the GNU Interactive Tools package.

   Copyright (C) 1993, 1994, 1995 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

The GIT wipe file utility
=========================

   `gitwipe' is an utility for wiping files. It overwrites the file
contents with a random sequence of numbers and then calls `sync'().

   Note that `gitwipe' does *not* delete the file since (under `Linux'
at least) the `sync'() system call might return before actually writing
the new file contents to disk.  Deleting the file might be dangerous
because some file systems can detect that the blocks in the file are no
longer used and never write them back to disk in order to improve
performance.  It is up to you to delete the file(s) at a later moment.

The GIT mount utility
=====================

   `gitmount' is a script that allows you to mount any block device
without specifying the file system type.  You may now insert the floppy
in the drive and type '`gitmount' `fd0'' and the first floppy will be
mounted in the directory `/mnt/fd0'.

   You don't need to know the file system type anymore.  The directories
`/mnt/fd0' and `/mnt/fd1' must exist.  If you want to use `gitmount'
with the block device `/dev/xxx' then the directory `/mnt/xxx' must
exist too.

The GIT per file type action script
===================================

   `gitaction' is a script that executes a different action for each
file type specified.  It is called by the `git' program when pressing
`F2' or `^Xa'.

   The first parameter is the current directory name and the second one
is the file name to be matched against the default patterns.  The
matching is done using the shell 'case' statement.

   If you press `F2' or `^Xa' on a `*.c' file, `git' will compile it,
if you press `F2' or `^Xa' on a `*.tar.gz' file, `git' will list the
tar archive contents, if you press the same keys on a `*.gz' file,
`git' will display its uncompressed contents on the screen, etc ...

   By default `gitaction' checks for the following patterns:

"*.cc"  "*.c"  "*.l"  "*.y"  "*.h" "*.s" "*.S" "*.o" "*.a" "*.sa"
"Makefile" "makefile" "*.tar.gz" "*.tgz"  "*.tar.z" "*.tar.Z"  "*.taz"
"*.tar"  "*.gz"  "*.z"  "*.Z"  "*.doc" "*.txt" "*.gif" "*.jpg" "*.tif"
"*.bmp" "*.fli" "*.flc" compressed/uncompressed manual pages

and acts as appropriate.  If no pattern is found, the file is displayed
using `more'.  Feel free to change this.

   If you want to find out what the default action for each file type is
(or if you want to modify it), just read/modify the `gitaction' script.

   If you press `F2' or `^Xa' on a `*.gif' file or `*.jpg' file and you
have the `zgv' utility installed, you will be able to see it.  If you
want to change the gif/jpeg viewer, all you need to do is to change its
name in the `gitaction' script.  I don't know a `*.bmp' or `*.tif'
viewer.  Feel free to add one in the `gitaction' script.

The GIT stdout to stderr redirection script
===========================================

   `gitredir' is a very small script that fools the `git' program,
making it believe that the command started wrote something to standard
error.  It was not designed to be used as a stand alone program.

   `gitredir' is useful for programs like `du'.  We are interested in
du's output and we would like to write it on the status line
(especially the output of the 'du -s' command).  Normally, this is not
possible because 'du -s' will display the information on the standard
output (`git' catches only standard error) and will exit with the exit
code 0.  `git' will display the standard error contents on the status
bar only if the program exit status is not 0.

   So, `gitredir' starts a program, sends its standard output through a
pipe to a sub-shell which read from the pipe and write to standard
error.  After that, `gitredir' exits with the exit code 1.  This way,
`git' thinks that an error occured and display the standard error
redirection file to the status bar.  Stupid, but useful.

The GIT recursive grep script
=============================

   `gitrgrep' is a very small script that calls `grep' recursively.  It
accepts `grep' like options / parameters, the only difference being
that file specifications should be quoted:

             `gitrgrep' main '*.c'

     or

             `gitrgrep' errno '*.c *.h'

   `gitregrep' and `gitrfgrep' are recursive versions of the egrep and
fgrep programs.

Customizing GNU Interactive Tools
*********************************

Environment Variables
=====================

   The configuration files use shell environment variables to call the
shell, editor, mail reader, compress and virtual memory status utility.
That means that if you set GIT_SHELL, GIT_EDITOR, GIT_RMAIL,
GIT_COMPRESS or GIT_VMSTAT to some value, that value will be used
instead of the default one.  The defaults are:

     	GIT_SHELL='/bin/sh'
     	GIT_EDITOR='vi'
     	GIT_RMAIL='emacs -f rmail'
     	GIT_PAGER='more'
     	GIT_COMPRESS='gzip -9'
     	GIT_VMSTAT='free'

   If SHELL is defined, GIT_SHELL will be set to that value.  If EDITOR
is defined, GIT_EDITOR will be set to that value.  If you want to
change the default settings, put something like this into your
`.profile':

     	export GIT_SHELL='/usr/local/bin/bash'
     	export GIT_EDITOR='emacs'
     	export GIT_RMAIL='elm'
     	export GIT_PAGER='less'
     	export GIT_COMPRESS='compress'
     	export GIT_VMSTAT='vmstat'

Configuration Files
===================

   There is one configuration file per terminal type in `GIT'.  The
configuration file(s) reside in the user's home directory or (the
default versions) in the directory `$(prefix)/lib' (usually
`/usr/local/lib').

   Their generic name is `.gitrc.TERM'.  `GIT' allows each terminal
type to have its own configuration file (TERM is the value of the TERM
environment variable (e.g `vt102'); for the `Linux' console the
configuration file is `.gitrc.console').

   Since most of the key bindings are common to all the terminal types,
a configuration file called `.gitrc.common' is parsed before parsing
the normal `.gitrc.TERM' configuration file, the later one defining
only those keys that are terminal specific.  However, if a key binding
is redefined in the `.gitrc.TERM' file, that binding will be used.

   If the `GIT' package have been compiled without passing the
`--enable-terminfo' option to the `configure' script and your system
has a huge `termcap' database (`/etc/termcap'), you can copy the
termcap definition(s) of your terminal(s) in a file called, lets say
`.termcap' and put it in your home directory.  After that, set your
TERMCAP environment variable to point to it.  You should add something
like this to your `.profile':

     TERMCAP=`/home/mike/.termcap'

   The interactive programs in the `GIT' package can run without such a
file, but on systems with huge `termcap' databases, copying the
definitions of the most used terminals in a local `.termcap' file will
lead to a faster start.

   The `.gitrc.TERM' it is first time searched in the home directory
then, if not found, in the directory `$(prefix)/lib' (usually
`/usr/local/lib'). The configuration file is structured on sections,
each section containing variables in the following format:

     	`variable-name' = `first-field';`second-field'; ...

   After the `variable-name' at least one space or tab is required.
All characters after a `#' are ignored and if you comment a section
name, the whole section is ignored.

   Section names are enclosed in rectangular brackets (`[' and `]').
Note that this manual don't include them while refering to section
names.

   The `GIT' package contains three major programs: `git', `gitps' and
`gitview'.  Each one has its own sections in the configuration files.
There is also a global setup section called `Setup' that is used by all
these programs.

Writing key sequences
---------------------

   `GIT' contains three interactive programs.  Their names are: `git'
(this is the file system browser), `gitps' (this is the process
viewer/killer and `gitview' (this is the ASCII/HEX file viewer).  Each
one of these programs has its own set of key bindings.

   The convention used in describing key bindings are very simple.  Here
there are some examples that will help you to understand them.  The
corresponding `Emacs' conventions will help you even more.

   `^A' means keeping the Ctrl key down and pressing the `a' key
(`C-a').

   The `ESC' character is represented as `^[' so that you can use the
meta character (`M-' ) where available (or the `ESC' key):

   `^[a' corresponds to `M-a' (pressing the `ESC' key and then `a').

   The `^' character is represented as `^^'.

   The `backspace' character is represented as `^_'.

   The `Ctrl-SPACE' character (`C-SPC') is represented as `^$'.

   The space (`SPC') character is represented as `^@'.

   Note that the key bindings notation described here is only used in
the configuration files.  For the sake of readability this manual uses
`ESC' for the `ESC' key, `SPC' for the `SPACE' key and `RET' for the
`RETURN' (`ENTER') key.

The global setup section
------------------------

   In this section the variables have only one field.

`TempDirectory'

   This variable specifies the location of the temporary files created
by `git'.

`AnsiColors'

   This variable should be set to `ON' if the terminal supports
standard `ANSI' color sequences.  Otherwise it should be `OFF'.  If
`AnsiColors' is `ON', `GITxxx-Color' sections will be used in the
configuration files `.gitrc.TERM'.  Otherwise, `GIT' interactive
programs will use the `GITxxx-Monochrome' sections.

`UseLastScreenChar'

   This variable is used for terminals that can't write on the last
character of the screen without scrolling the entire screen.  If your
terminal has no problem writing there (`Linux' console, vt100, vt102,
xterm, ...)  set it to `ON'.  Otherwise (hpterm), it should be `OFF'.

`StartupScrollStep'

   This variable specifies the scroll step initial value for both
panels.

git Sections
------------

git Setup
.........

   In this section the variables have only one field.

`StartupFileDisplayMode'

   This variable specifies the file specific information displayed at
startup.  It can be any of `OwnerGroup', `DateTime', `Size', `Mode' or
`FullName'.  Its value initially affects both panels but it can be
changed separately afterward.

`StartupFileSortMethod'

   This variable specifies the startup sort method.  It can be any of
`Name', `Extension', `Size', `Date', `Mode', `OwnerId', `GroupId',
`OwnerName' or `GroupName'.  Its value initially affects both panels
but it can be changed separately afterward.

`ConfirmOnExit'

   If this variable is `ON', the user is prompted for confirmation at
exit.

`HistoryFile'

   This variable specifies the history file name.  The default value is
`~/.githistory'.

`InfoDisplay'

   If this variable is `OFF', auxiliary file informations are not
displayed.  This can be useful if you are using a very slow terminal.

`LeadingDotMatch'

   If this variable is `OFF' when matching files for
select-files-matching-pattern / unselect-files-matching-pattern then the
leading '.' in the file name is matched only explicitly.

`TypeSensitivity'

   If this variable is `OFF', colors are not used when displaying
files.  Normally, the information in the `GIT-FTI' section is used to
display files with different colors, depending on their types.  Note
that `TypeSensitivity' is automatically set to `OFF' when `AnsiColors'
is `OFF'.  See GIT-FTI, for mor information.

`NormalModeHelp'

`CommandLineModeHelp'

   These variables describe the status bar contents for each `git' mode
when no errors occurred.  `git' can display on the status bar a help
string and/or some system information (system type, hostname, machine
type and the current date) using escape characters:

             \s      ->      the system type
             \h      ->      the host name
             \m      ->      the machine type
             \d      ->      the current date
   Modes, for more information.

Using git on colors displays
............................

   In this sections the variables have only one field.

   These section allows you to customize the colors of `git'.  Reading
the `.gitrc.TERM' configuration file is self explanatory.

Using git on monochrome displays
................................

   In this sections the variables have only one field.

   These section allows you to customize the appearance of `git' on
monochrome displays. Reading the `.gitrc.TERM' configuration file is
self explanatory.

Defining keys
.............

   These section describes the actions `git' takes when a specified key
is pressed.  A variable can have up to 6 fields separated by ';'.  Each
line in this section looks like:

     `key-sequence' = `command-name';`formatted-command';`new-dir';
                    `save-screen';`pause';`hide'

   Note that you can't continue the variable fields description on the
next line.

The key-sequence field
......................

   `key-sequence' is the key sequence associated with the given
command.  You can use any key sequence that doesn't start with an ascii
character (0x20 to 0x7e).

   Symbolic key names (`F0', `F1', `F2', ... `F10', `UP', `DOWN',
`RIGHT', `LEFT', `INS', `DEL', `HOME', `END', `PGUP' and `PGDOWN') can
be used instead of the key sequence.  If some keys don't have a
`termcap'/ `terminfo' description (like the `F11'/`F12' keys on the
`Linux' console) you can specify the key sequence in the usual way.

The command-name field
......................

   `command-name' is a command generic name.  Even if it is not always
used, the `command-name' must be present (if a command is associated
with a `key-sequence').  If it is not, no action will be taken when
pressing `key-sequence'.

   There are two types of commands in `git': built-in commands and user
defined commands.  If the `command-name' section contains a built-in
command specification, the other fields are ignored.

   Note that by convention built-in command names contain only lower
case letters while user defined command names contain only upper case
letters.

The formatted-command field
...........................

   - `formatted-command' is a shell command which can contain some
scanf like format specifiers.  They are used to get the current entry
name, owner, group, mode, etc.

   Note that using uppercase `format specifiers' you will be able to
access the other panel path, file and directory names, etc.

   These are the available `format specifiers':

The %s format specifier
.......................

   The format of %s is:  %s{question,default_answer}.

   When `git' encounters a %s in the `formatted-command' it asks the
user the question `question' whose default answer is `default_answer'
and replaces the `%s{ , }' with the user's answer.  Both `question' and
`default_answer' can contain any other `format specifiers' except %s.

   Note that there should be no spaces between %s and '{'.

The %f format specifier
.......................

   `git' will replace %f with the current directory entry name only if
it is a file (not a directory).

The %d format specifier
.......................

   `git' will replace %d with the current directory entry name only if
it is a directory (not a file).

The %l format specifier
.......................

   `git' will replace %l with the current directory entry name only if
it is a symbolic link with no target.

The %t format specifier
.......................

   `git' will replace %t with the current directory entry name only if
it is a named pipe.

The %z format specifier
.......................

   `git' will replace %z with the current directory entry name only if
it is a socket.

The %a format specifier
.......................

   `git' will always replace %a with the current directory entry name.

The %m format specifier
.......................

   `git' will always replace %m with the current file mode.

The %g format specifier
.......................

   `git' will always replace %g with the current file group.

The %o format specifier
.......................

   `git' will always replace %o with the current file owner.

The %p format specifier
.......................

   `git' will always replace %p with the current panel path.

The %b format specifier
.......................

   `git' will always replace %b with the current panel directory name.

The %i format specifier
.......................

   `git' will always replace %i with all the current panel selected
file names.

The %? format specifier
.......................

   The format of %? is: %?{confirmation}.

   `git' uses this format specifier only to ask for confirmation before
expanding / executing the current command.  The `confirmation' string
is displayed and, if the user doesn't confirm, the command is aborted.
Otherwise, %?{confirmation} expands to a null string and the command is
expanded / executed normally.

The new-dir field
.................

   If the `formatted-command' successfully exits (exit code = 0) or it
has no body and this field is present then `new-dir' will become the
current panel directory.

   The character '~' used at the beginning of the `new-dir' field is
replaced by the user's home directory.

The save-screen field
.....................

   This field is a character (usually 'y' or 'n') that tells `git' to
save ('y') or not to save ('n') the terminal's screen after executing
the `formatted-command'.  Saving the screen is not necessary while
editing or viewing a file because the information left after the editor
or the viewer exits is not important.  Saving the screen means that that
screen will be restored before the execution of the next command.
Currently this field is used only if you are working as a super user
under `Linux' on a virtual console.  Its default value is 'y'.

The pause field
...............

   Users may wish to read some commands's results before repainting the
panels.  If this field is present git will wait for a key to be pressed
before restoring the panels.  Its default value is 'n'.

The hide field
..............

   Some commands that don't displaying any useful information if
successfully complete their execution: `mount', `chmod', `chown',
`chgrp', `sync' ... and, if an error occurs, a line or two are sent to
stderr.  If this option is 'y', the stdout and stderr will be
redirected to some files (stdout.pid and stderr.pid, where pid is
`git''s pid) and only if the command's exit code is not 0, the
stderr.pid file will be displayed, line by line, onto the status bar.
This way the panels will not be deleted and then repainted and the
command appears to be built-in.  stdout.pid and stderr.pid are created
in the `TempDirectory' specified in the `Setup' section.  Its default
value is 'n'.

Setting up colors for different file types
------------------------------------------

   This sections contains entries of the form:

     `pattern' = `foreground'; `background'; `brightness'

where `pattern' is a file name matching pattern, `foreground',
`background' and `brightness' are the color specification to be used
when a file whose name match the given `pattern' is displayed in a
panel.  Colors can be turned off using the `TypeSensitivity' variable
in the `GIT-Setup' seection.

gitps Sections
--------------

gitps Setup
...........

   In this section the variables have only one field.

Using gitps on color displays
.............................

   In this sections the variables have only one field.

   These section allows you to customize the colors of `gitps'.
Reading the `.gitrc.TERM' configuration file is self explanatory.

Using gitps on monochrome displays
..................................

   In this sections the variables have only one field.

   These section allows you to customize the appearance of `gitps' on
monochrome displays. Reading the `.gitrc.TERM' configuration file is
self explanatory.

Defining keys
.............

gitview Sections
----------------

gitview Setup
.............

   In this section the variables have only one field.

Using gitview on color displays
...............................

   In this sections the variables have only one field.

   These section allows you to customize the colors of `gitview'.
Reading the `.gitrc.TERM' configuration file is self explanatory.

Using gitview on monochrome displays
....................................

   In this sections the variables have only one field.

   These section allows you to customize the appearance of `gitview' on
monochrome displays. Reading the `.gitrc.TERM' configuration file is
self explanatory.

Defining keys
.............

GNU Interactive Tools limitations
*********************************

   Background commands (& terminated)can be specified in the
configuration file but their result (stdout and stderr redirection),
will be overwritten by the result of newer commands and, if an error
occurs, it will not be seen.

   When `git' is compiled for `Linux', the default built-in color
descriptions are for color monitors, so you can't (decently) run `git'
on a b/w monitor without the `.gitrc.TERM' file correctly configured.
`.gitrc.TERM' should be configured with `AnsiColors' = OFF.

   Job support is implemented only in `git'.

   Due to the fact that the ';' character is used as a field separator
in the configuration files, you can't write something like that in the
`.gitrc.TERM' files:

   ^AAA = SHOW-USERS-AND-GROUPS; more /etc/passwd; more /etc/group

because 'more /etc/group' will be considered as a directory to switch
to.  You must write a small script instead:

   #!/bin/sh

   more /etc/passwd more /etc/group

   Supposing the script name is `show_ug', the `.gitrc.TERM' line will
look like this:

   ^AAA = SHOW-USERS-AND-GROUPS; show_ug

   There is no support for appearance modes on magic-cookie terminals.

GNU Interactive Tools bugs
**************************

   Any questions, comments, or bug reports, should be emailed to the
authors.  Please be sure to include the version number.  The email
addresses are:

             tudorh@pub.ro
             pink@pub.ro