GNU Interactive Tools - Customizing GNU Interactive Tools

Go to the first, previous, next, last section, table of contents.

# Customizing GNU Interactive Tools

- Environment Variables: Environment variables used by GIT
- Configuration Files: GIT's configuration files

## 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, 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_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_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.

- Key Sequences: How to write a key sequence.
- Setup: The global setup section.
- git Sections: git's sections.
- gitps Sections: gitps's Sections.
- gitview Sections: gitview's Sections.

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

``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: git's setup section.
- GIT-Color: git's color section.
- GIT-Monochrome: git's monochrome section.
- GIT-Keys: git's keys section.
- GIT-FTI: git's file type information section.

#### 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 section Setting up colors for different file types, 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

See section Panel 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.

- key-sequence: The key-sequence field.
- command-name: The command-name field.
- formatted-command: The formatted-command field.
- new-dir: The new-dir field.
- save-screen: The save-screen field.
- pause: The pause field.
- hide: The hide field.

#### 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'`:

- %s: The %s format specifier.
- %f: The %f format specifier.
- %d: The %d format specifier.
- %l: The %l format specifier.
- %t: The %t format specifier.
- %z: The %z format specifier.
- %a: The %a format specifier.
- %m: The %m format specifier.
- %g: The %g format specifier.
- %o: The %o format specifier.
- %p: The %p format specifier.
- %b: The %b format specifier.
- %i: The %i format specifier.
- %?: The %? format specifier.

#### 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 entry 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 (``git.1.pid'` and ``git.2.pid'`, where pid is `git`'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'.

### 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: gitps's setup section.
- GITPS-Color: gitps's color section.
- GITPS-Monochrome: gitps's monochrome section.
- GITPS-Keys: gitps's keys section.

#### gitps Setup

In this section the variables have only one field.

``Help'`

This variable describe `gitps`'s status bar contents.

#### 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: gitview's setup section.
- GITVIEW-Color: gitview's color section.
- GITVIEW-Monochrome: gitview's monochrome section.
- GITVIEW-Keys: gitview's keys section.

#### gitview Setup

In this section the variables have only one field.

``Help'`

This variable describe `gitps`'s status bar contents.

#### 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

Go to the first, previous, next, last section, table of contents.