gviewglob(1) · carta

NAME

viewglob, gviewglob - shell add-on for windowing environments.

SYNOPSIS

viewglob [options]
gviewglob [options]

DESCRIPTION

Viewglob is a utility which supervises your shell activity and tracks file selections and globs in a display showing the layout of relevant directories. The display is written in GTK+, so Viewglob requires that the shell be run in an X terminal (e.g. xterm, rxvt, etc.).

Viewglob should be compatible with any recent version of bash or zsh, and doesn't assume any particular shell configuration.

Note: either name is equivalent for calling the program.

OPTIONS

This program follows the usual GNU command line syntax, with long options starting with two dashes. A summary is included below.

-c, --shell-mode=name: Shell to be used. name can be "bash" or "zsh" (default is bash).

-d, --display=path: Use an alternate display program.

-f, --config-file=path: Use an alternate config file (~/.viewglobrc is the default).

-o, --shell-output=filename: Copy a transcript of the shell's output to the given file. Note that this keeps the terminal sequences intact, so a cat of the file will be a perfect repeat of the session. Be careful, the file will grow quickly!

-O, --term-output=filename: Output a transcript of the terminal's input to the given file. This is the stuff that you've typed, without any of the shell interpretation.

-s, --sort-style=<windows|ls>: Sort files with dirs first (Windows) or purely by name (ls). ls mode is the default.

-r, --dir-order=<descending|ascending|ascending-pwd-first>: List directories in descending order (the default), ascending (last referenced directory has the top listing), or ascending with the current directory always first.

-n, --show-max=number: Maximum number of files to show in the display for each directory. A [Results Truncated] indicator will show if the max has been reached. Note that you can always force show all files with the context menu. If --show-max is passed 0, there is no limit.

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

-b, --disable-icons: Don't show file type icons in the display.

-t, --disable-star: Disable the asterisk icon at the beginning of your shell prompt when in a Viewglob-supervised shell.

-m, --disable-smart-insert: File and directory names from the display are always inserted to the terminal escaped and without space padding.

-w, --show-hidden: Never hide hidden files (ha).

-e, --executable=path: Use the given executable as the shell instead of its first reference in the path. Note that if this isn't a version of the shell chosen with --shell-mode, it won't do you much good, and could be harmful.

-h, --help: Show summary of options.

-V, --version: Show the version of the program.

USAGE

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 window is a textbox with your command line. This is what Viewglob is actually globbing 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.

Navigation

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

Up:: k, p, or <Up Arrow>

Down:: j, n, or <Down Arrow>

Page Up:: b, u, or <PgUp>

Page Down:: f, d, or <PgDown>

Toggle on/off:: <SPACE>

Refocus windows:: <TAB> or <ENTER>

Their C- counterparts also work. To enter a real C-g to the shell, type it twice. If the display is killed or closed through the window manager (e.g. you clicked the little "x" icon), it's only been toggled off. To get it back, type C-g <SPACE> in the terminal.

To disable Viewglob functionality (i.e. close the display and stop tracking the command line, etc.), you can type C-g q. Once Viewglob has been disabled in this manner, it can't be re-enabled without exiting.

The refocus shortcut will send a quick request to the window manager to activate both the display and terminal in sequence, with the result that both will be above any other windows and one of them will have the focus (but which one is determined by the WM). Note that this may not work for WMs which are lazy on the EWMH specification.

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. By default Viewglob is in "smart-insert" mode, which means it inserts the names or paths the way it thinks you want to (but may be wrong sometimes -- it's "smart" as defined by Microsoft). Smart-insert 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.

If smart-insert has been disabled with the --disable-smart-insert flag, the file/directory names/paths are always inserted escaped but without 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.

Display Peculiarities

If the number of files in a shown directory is above the given max, Viewglob will truncate the results (with an indicator). You can force Viewglob to display the contents of the whole directory by right-clicking the heading for the listing and choosing "Show all files". By default hidden files are not shown, but you can view them using the same mechanism.

Directories referenced in several different ways will always be interpreted as the same directory if they're on the same device and have the same inode (i.e. they are indeed the same). Therefore these three names are equivalent to Viewglob (and a trailing slash does not differentiate a directory from one without a trailing slash):

: /usr/local/lib/
/usr/local/lib/./
/usr/local/lib/../lib/

Note however that the name of the first reference will be the name that appears in the Viewglob display. So if you refer to files in /usr/local/../local/lib and then /usr/local/lib on the same command line, Viewglob understands they are the same directory, but will use the less practical name /usr/local/../local/lib, since it appears first (and is just as valid as /usr/local/lib)

Since people generally don't type such things as /usr/local/../local/lib, this shouldn't be an issue.

FILES

~/.viewglobrc

: If present, this file specifies a default configuration for Viewglob. The file syntax is:

: <long_option_name> [ <whitespace> <value> ]

: So, to always use zsh, disable the asterisk at the prompt, use a display limit of 700, show hidden files, and use Windows-style sorting, the file should contain:

shell-mode: zsh

disable-star

show-max: 700

show-hidden

sort-style: windows

: The configuration file has a lower priority than options specified on the command line, and can be disregarded completely with -f.

NOTES

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:

: http://viewglob.sourceforge.net/

ENVIRONMENT VARIABLES

HOME: The location of the default configuration file.

LS_COLORS: Used by the display as described in dir_colors(5).

If you encounter an issue where certain filenames do not show in the display and you are using an encoding other than UTF-8, you may want to read about the other GLib environment variables:

: http://developer.gnome.org/doc/API/2.0/glib/glib-running.html

For example, for iso8859-1, run:

: G_FILENAME_ENCODING=ISO-8859-1 viewglob

BUGS

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.

AUTHORS

Stephen Bach <[email protected]>