viewglob(1) convenience wrapper script for the Viewglob package


viewglob [options]


Viewglob supervises interactive shell activity and tracks file selections and globs in a graphical display showing the contents of relevant directories.

The viewglob command is a convenience wrapper for two other programs in the Viewglob package which do the actual work, vgseer(1) and vgd(1). You will want to use those programs directly to do things that are non-simple.

If this script is run from a terminal, that terminal will be used. Otherwise the default terminal program will be determined using gconftool-2(1), with xterm as the fallback.

General information about using Viewglob can be found on this manpage under USAGE.


This program follows the usual GNU command line syntax, with long options starting with two dashes. A summary is included below.
-h, --host=<name>
Connect a new vgseer process to a vgd process on the given host. You should only specify this if you are not connecting to your local machine.
-p, --port=<number>
Connect a new vgseer process to a vgd process on the given port. If it is a local connection and there is no vgd active on the port, one will be started. The default port for Viewglob is 16108 (1-GLOB). By default Viewglob will communicate over a Unix-domain socket for a local vgd instance, but will still listen on the specified port for remote connections.
-c, --shell-mode=<name>
Shell to be used. name can be ``bash'' or ``zsh'' (default is bash).
-t, --shell-star=<on/off>
Show or hide the asterisk character which is usually at the beginning of a vgseer shell prompt.
-d, --display=<vgmini|vgclassic|[path]>
Display program. The Viewglob package comes with vgclassic and vgmini (the newer display). Though there aren't any other displays in existence at this point, one could be used by passing its path. The default is vgmini.
-s, --sort-style=<windows|ls>
In the display, sort files with directories first (Windows) or purely by name (ls). ls mode is the default.
-r, --dir-order=<descending|ascending|ascending-pwd-first>
In the display, list directories in descending order (the default), ascending (last referenced directory has the top listing), or ascending with the current directory always first.
-z, --font-size-modifier=<+/-##>
Increase or decrease the base font size in the display by the given number. E.g. ``-z +2'' increases the window manager's default by 2, while ``-z -2'' decreases the default by 2.
-i, --file-icons=<on/off>
Show or hide the file type icons in the display.
-H, --help
Show summary of options.
-V, --version
Show the version of the package.
Note that vgseer and vgd have further options when used directly.


When you start Viewglob, you'll be presented with your familiar prompt and a new window showing the file layout of the current directory. As you begin to type a command, the display window will highlight to show potential filename completions (dull highlight) and file selections and globs/expansions (vibrant highlight). Also, as you reference other directories (e.g. ../ or /usr/local/), their layouts will appear as well.

At the bottom of the display is the command line. This is what Viewglob is actually basing its results on; if you find the display is not showing what you expected, check to make sure the display's command line is the same as the one in the shell, as they can be different (see NOTES below).

With a few exceptions, any text you type into the display is passed to the terminal as input. So if you wished, you could use the display as your interface to the shell -- this actually works quite well if you're doing a lot of file management. Arrow keys, Page Up, Page Down, Home, and End are interpreted by the display and not passed to the terminal.

If you start other Viewglob-supervised shells, they will share the display if they connect to the same vgd process (default). Whichever terminal is currently active (i.e. has window focus or is being typed in) will have its environment shown.

Display Navigation

You can navigate the display from the terminal by pressing C-g (Ctrl-G) followed by a direction character. They are:

C-k, C-p, or <Up Arrow>
C-j, C-n, or <Down Arrow>
Page Up:
C-b, C-u, or <Page Up>
Page Down:
C-f, C-d, or <Page Down>

To enter a real C-g to the shell, type it twice. Navigation commands can be chained together - for example, typing C-g C-f C-f C-k will page down twice and then move up once. The chain is broken when a non-navigation character is typed.

In vgmini, the default display program, Up and Down are used to switch between viewable directories, while Page Up and Page Down are used to navigate the currently viewed directory.


There are four Viewglob commands in addition to display navigation. After typing C-g:

Set or clear mask:
Toggle on/off:
Refocus window:

Toggling will close the display if it's active or open it if not. It's completely safe to open and close the display multiple times.

The behaviour of the refocus command is affected by the following:

The display program used.
The vgd execution options.
The location of the display in relation to the active terminal.

Generally it tries to ensure that both the terminal and the display are viewable at the same time, and if they already are, it switches the focus between the display and the active terminal (sort-of like an internal Alt-<TAB>).

If the display did not automatically update to the current shell after a window shuffle (i.e. it's showing the environment of a different shell), refocusing will wake it up. This is often necessary for tabbed terminals like gnome-terminal and konsole.

Disabling Viewglob functionality disconnects the terminal from vgd and turns vgseer off, resulting in an almost regular shell. There is no way to re-enable Viewglob in a shell which has been disabled.

Filename Masking

File masking is a way to control the number and types of files shown in the display. The default mask is "*", which shows all non-hidden files. To show ALL files, an appropriate mask would be ".* *". To show only C source files, the mask could be "*.[ch]" or "*.c *.h". To just display directory file types, the mask would be "*/".

A mask can be set with the key sequence C-g [mask] <ENTER>. The mask string will print in the display as it's being typed. Typing a non-printable character (such as <ESC> or C-c) while creating a new mask will cancel it. The mask can be set back to the default "*" with a simple C-g <ENTER>.

File masking is done on the client level. Therefore, when using Viewglob with a remote machine, a conservative file mask could improve response time a little.

File/Directory Name Insertion

The name of any file or directory can be passed to the terminal by double left-clicking. If shift is held, the full path of the file or directory is passed. Insertion works as follows:

If you are currently at the command line (i.e. the shell has control of the terminal):
Special characters (*, ?, !, etc.) are escaped.
If there is no whitespace to the left of the cursor, a space is prepended to the inserted text.
If there is no whitespace to the right of the cursor, a space is appended to the inserted text.

If you are executing another program in the terminal (say a text editor or something):
The text is inserted as-is, without any escaping or spacing.

Note that insertion of file names works pretty much the same as just pasting text into the terminal -- it's interpreted only as a series of keystrokes. This means it's your responsibility to be sure that the shell is in a state cooperative to the reception of text. For example, if you use vi-mode in your shell, and you insert a file name while you're in command mode, the shell will receive the data as a series of commands - probably not what you wanted to do.


If present, these file specify a default configuration for Viewglob. See the manuals for vgseer(1) and vgd(1) for more information.


First of all, when I say below ``such-and-such feature of bash/zsh doesn't work in Viewglob'', I just mean that the display will not show expansion information for that feature. The functionality of both shells is UNCHANGED by running Viewglob. Anyhow.

Unfortunately, I haven't found a good way to predict history expansion (stuff involving the special char ``!''). The Viewglob display will pretend any construction starting with an unescaped ! does not exist. Exceptions: a ! by itself, or the !(foo) pattern match.

A Viewglob'd shell session will not extend to subshells. That is, if while in a Viewglob session you run, say, ``bash'' or ``su'', Viewglob will probably be temporarily disabled until you exit the new shell. This is a consequence of Viewglob's implementation, but I'd probably keep this behaviour even if I could get around it.

Since Viewglob doesn't track changes in shell variables, I've decided to take out variable interpretation entirely. If Viewglob sees what it thinks is a variable in its command line, it'll stop processing it until it's removed. The variables will of course work fine in the shell itself.

While running Viewglob, don't unset or change the following variables and functions.

In bash: PS1, PROMPT_COMMAND, histchars;
In zsh: PROMPT (or PS1), RPROMPT, precmd, TRAPHUP;

Viewglob would probably become confused. Note that if you do change one of these (maybe you were curious, or you just forgot), it won't affect the shell you were using, just the display.
If you want to modify these variables, do so outside of a Viewglob session, or put your changes in the shell's run control file.

Only the first command in a compound command will be interpreted by Viewglob. For example, as you type:

$ mv *.jp{e,}g ~/photos/ && rm *

Viewglob will stop listening when it sees ``&&'', and the display will only register *.jp{e,}g. This isn't an implementation problem - it's just that showing globbing for the subsequent commands could be deceptive, as the filesystem could be changed by executing the first command (as it is in this case).

Command substitution (stuff with backticks (`) or $(command)) is ignored by Viewglob for the reason given above. Works fine in your shell though.

The display will not interpret aliases in zsh.

For more information, please visit:


Tabbed terminal programs such as gnome-terminal and konsole confuse the active-terminal-tracking functionality (use the refocus command to tell Viewglob you've changed shells).

Command line tracking seems to be pretty good for general use, but is far from perfect.

Resizing the terminal window after you've typed a multi-line command will often cause Viewglob's command line to become temporarily out of sync with the true command line, though it tries really hard to keep up. No big deal if this happens -- Viewglob should be in sync by the start of the next command.

And there are certainly others. If you spot any bugs (and they aren't explained by NOTES above), send me a message, okay? Ideas and code contributions are also very welcome.


Stephen Bach <[email protected]>