4. Customizing GNU Interactive Tools

4.1 Environment Variables

The configuration files use shell environment variables to call the shell, editor, mail reader, html viewer, compress and virtual memory status utility. That means that if you set GNUIT_SHELL, GNUIT_EDITOR, GNUIT_RMAIL, GNUIT_BROWSER, or GNUIT_VMSTAT to some value, that value will be used instead of the default one. The defaults are:

	GNUIT_SHELL='/bin/sh'
	GNUIT_EDITOR='vi'
	GNUIT_RMAIL='emacs -f rmail'
	GNUIT_PAGER='more
	GNUIT_VMSTAT='free'
	GNUIT_BROWSER='lynx'

if the configure script is passed ‘--enable-debian’, some of the defaults are changed as follows:

	GNUIT_EDITOR='sensible-editor'
	GNUIT_PAGER='sensible-pager'
	GNUIT_BROWSER='sensible-browser'

If SHELL is defined, GNUIT_SHELL will be set to that value. If PAGER is defined, GNUIT_PAGER will be set to that value. If EDITOR is defined, GNUIT_EDITOR will be set to that value. If you want to change the default settings, put something like this into your ‘.profile’:

	export GNUIT_SHELL='/usr/local/bin/bash'
	export GNUIT_EDITOR='emacs'
	export GNUIT_RMAIL='elm'
	export GNUIT_PAGER='less'
	export GNUIT_VMSTAT='vmstat'
	export GNUIT_BROWSER='netscape'

These variables used to be prefixed with GIT_ (e.g. GIT_PAGER). The old names are still accepted for backwards compatibility.

4.2 Configuration Files

There is one configuration file per terminal type in GNUIT. The configuration file(s) reside in the user's home directory or (the default versions) in the directory ‘/usr/share/gnuit/’). Files in the user's home directory start with a leading “.”

Their generic name is ‘gnuitrc.TERM’. GNUIT 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 ‘gnuitrc.console’).

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

If the GNUIT 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 GNUIT 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 ‘.gnuitrc.TERM’ is first searched for in the home directory then, if not found, in the directory ‘/usr/share/gnuit/’). (without the leading “.”). The configuration file is structured in 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 GNUIT package contains three major programs: gitfm, 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.

Note that now git has been renamed to gitfm, the corresponding sections have been renamed to GITFM, however for backwards compatibility, the old name (GIT) is still checked if the GITFM section is not found.

4.2.1 Writing key sequences

GNUIT contains three interactive programs. Their names are: gitfm (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.

4.2.2 The global setup section

In this section the variables have only one field.

‘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 ‘gnuitrc.TERM’. Otherwise, GNUIT 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.

4.2.3 gitfm Sections

4.2.3.1 gitfm 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’, ‘AbbrevSize’, ‘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.

‘MaxUnscaledDigits’

Maximum number of digits a number may be before being scaled (e.g. to ‘123M’). If you want number to always be scaled, either set this to ‘0’, or set ‘StartupFileDisplayMode’ to ‘AbbrevSize’. Note that scaling may happen anyway if the number is too large for the display field.

‘GroupDigits’

If this variable is ‘ON’, digits of file sizes will be grouped according to your locale, (e.g. ‘123,456,789’).

‘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 ‘GITFM-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 section Setting up colors for different file types, for mor information.

‘NormalModeHelp’ ‘CommandLineModeHelp’

These variables describe the status bar contents for each gitfm mode when no errors occurred. gitfm 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

See section Panel modes, for more information.

4.2.3.2 Using gitfm on color displays

In this sections the variables have only one field.

These section allows you to customize the colors of gitfm. Reading the ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.3.3 Using gitfm on monochrome displays

In this sections the variables have only one field.

These section allows you to customize the appearance of gitfm on monochrome displays. Reading the ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.3.4 Defining keys

These section describes the actions gitfm 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.

4.2.3.5 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.

4.2.3.6 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 gitfm: 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.

4.2.3.7 The formatted-command field

‘formatted-command’ is a shell command which can contain some scanf(3)-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’:

4.2.3.8 The %s format specifier

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

When gitfm 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 '{'.

4.2.3.9 The %f format specifier

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

4.2.3.10 The %d format specifier

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

4.2.3.11 The %l format specifier

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

4.2.3.12 The %t format specifier

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

4.2.3.13 The %z format specifier

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

4.2.3.14 The %a format specifier

gitfm will always replace %a with the current directory entry name.

4.2.3.15 The %m format specifier

gitfm will always replace %m with the current file mode.

4.2.3.16 The %g format specifier

gitfm will always replace %g with the current file group.

4.2.3.17 The %o format specifier

gitfm will always replace %o with the current file owner.

4.2.3.18 The %p format specifier

gitfm will always replace %p with the current panel path.

4.2.3.19 The %b format specifier

gitfm will always replace %b with the current panel directory name.

4.2.3.20 The %i format specifier

gitfm will always replace %i with all the current panel selected entry names.

4.2.3.21 The %? format specifier

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

gitfm 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.

4.2.3.22 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.

4.2.3.23 The save-screen field

This field is a character (usually 'y' or 'n') that tells gitfm 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'.

4.2.3.24 The pause field

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

4.2.3.25 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 (‘git.1.pid’ and ‘git.2.pid’, where pid is gitfm's pid) and only if the command's exit code is not 0, the ‘git.2.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. ‘git.1.pid’ and ‘git.2.pid’ are created in the temporary directory specified in the TMPDIR environment variable (or "/tmp" if TMPDIR is not defined). The default value of the hide field is 'n'.

4.2.4 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 ‘GITFM-Setup’ section.

4.2.5 gitps Sections

4.2.5.1 gitps Setup

In this section the variables have only one field.

‘Help’

This variable describe gitps's status bar contents.

4.2.5.2 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 ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.5.3 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 ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.5.4 Defining keys

4.2.6 gitview Sections

4.2.6.1 gitview Setup

In this section the variables have only one field.

‘Help’

This variable describe gitps's status bar contents.

4.2.6.2 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 ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.6.3 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 ‘gnuitrc.TERM’ configuration file is self explanatory.

4.2.6.4 Defining keys

This document was generated by Ian Beckwith on March, 1 2009 using texi2html 1.78.