Ginsu Manual

Ginsu is a client for the gale chat system. It is designed to be powerful and above all stable, as well as having a quick learning curve.

Using Ginsu


These are the default keybindings. You may use the action name to rebind a key. See below for details.

Action NameDefault KeyDescription
Main Screens
show_help_screen<F1>, ?Show help screen
show_presence_status<F3>show presence status
show_puff_detailsdshow puff details
show_status_screenSshow status screen
Puff Movement
next_puffj, <Down>Goto the next puff
previous_puffk, <Up>Goto the previous puff
first_puff<Home>Goto the first puff
last_puff<End>, GGoto the last puff
next_line<Enter>, <C-E>Scroll one line down
previous_line<BackSpace>, <C-Y>Scroll one line up
next_page<C-F>, <PageDown>Scroll one page down
previous_page<C-B>, <PageUp>Scroll one page up
forward_half_page<C-D>Scroll a half page down
backward_half_page<C-U>Scroll a half page up
Filter Manipulation
prompt_new_filtercprompt new filter
prompt_new_filter_slash/prompt new filter slash
prompt_new_filter_twiddle~prompt new filter twiddle
pop_one_filterupop one filter
pop_all_filtersUpop all filters
invert_filter!invert filter
filter_current_threadt, Tfilter current thread
swap_filtersxswap filters
filter_current_authorafilter current author
Puff Body Filtering
toggle_rot13<C-o>toggle Rot13 filter
Mark/Workspace Manipulation
set_markmsave current position at a given mark.
recall_mark<SingleQuote>goto position saved at mark
set_filter_markMsave current filter stack at given mark.
recall_filter_mark<DoubleQuote>Recall filter stack at mark
recall_combine_markCRecall filter stack at mark and combine it with the current filter stack.
recall_workspace[1-9]Recall given numbered workspace and set it as current workspace, these follow marks [1-9]
Composing Puffs
new_puffpcompose a new puff
follow_upffollow up to the same category as the current puff
reply_to_authorrreply to the author of the current puff privatly
group_replygreply to the union of the sender and categories of the current puff
resend_puffRresend puff
goto_matchvvisit link in current puff
modify_presence_stringNmodify presence string
reconnect_to_servers<C-r>reconnect to servers
edit_config_fileEEdit the configuration file and reload its settings
ask_quitqquit ginsu
fast_quitQquit ginsu without asking first
redraw_screen<C-l>redraw screen


ginsu [OPTIONS]...  [categories]...

Available Options
-v, --verboseincrease verbosity output to errorlog.
-V, --versionprint version information
-s, --sample-configprint sample configuration file to stdout
-m, --manprint all internal help screens to stdout
-e, --justargsonly subscribe to command line arguments
-Pdo not write to pufflog
--helpshow this help screen
--nopufflogdo not read or write pufflog
--errorlog <FILE>log errors to file
--dumpkey <KEYFILE>print info for keyfile
--checkconfigcheck and print out configuration


Filters are used throughout ginsu. A filter is an expression which selects puffs which match it.

Filters are built up from primitives via conjunctions, disjunctions and grouping, allowing complex filters to be created.

a ; b - semicolons are used to mean OR. this matches if a OR b matches
a b - a space means AND. this matches if a AND b both match
(a b) ; c - filters may be grouped with parenthesis
!a - NOT. this matches if a does not match

primitive filters are regular expressions which are matched against the body of the puff, or a variety of special forms beginning with a ~ then a single character, then a colon, then the rest of the special form. If the text following the colon begins with a letter, the colon may be omitted. Arbitrary text may be used in filters by quoting it with single quotes.

Special Forms
~a:<gale-id>author of puff
~c:<category>category puff was sent too
~k:<regex>regex match against keywords
~s:<regex>regex match against senders real name
~b:<regex>regex match against message body
/<regex>search everything visible for regex
?truealways succeed
?falsealways fail
?signedpuff is signed
?encryptedpuff is encrypted

Examples of Filters:

 ( - all puffs by me
 ( - puffs from jtr and to
 ( /[gG]insu ; ~c:pub.gale.ginsu) - puffs containing the word ginsu or directed to pub.comp.ginsu
 ( /'(?i)john +meacham' ) - puffs with my name in them
 (!~k:^spoil) - no spoilers
 ( !~c:pub.meow) - puffs to buffy which are not about cats

The Filter Stack

There is always a current filter stack, which is a set of filters that determines which puffs are currently visible. there are a variety of keystrokes to modify the filter stack. If non-empty, the current filter stack is displayed on the bottom line of the main screen.

Environment Variables

which web browser to use in the default application hooks.
used if $VISUAL is not set.
name of alternate Gale configuration file to read. This does not change the name of the ginsu specific configuration file.
alternate location for user's gale directory. ~/.gale/ by default.
editor to use for composing puffs.

If any of these exist in the environment prefixed with GINSU_, they are preferred over the bare versions.

Configuration Options

Standard Gale Options Honored by Ginsu

The current gale domain.
Your gale id. default is $LOGNAME@$GALE_DOMAIN
Your real name used in puffs sent.
default presence string to send out.
This can be used to override which gale server to connect to.
List of categories to subscribe to. The default is some common public categories and your private address.

see also:

Ginsu Specific Options

beep on incoming puffs which match this filter.
set the web browser. This overrides the environment. This is only used by the default 'apphook' declarations. see below.
character set to assume files are in. This will become obsolete at some point.
do not install sigwinch handler. ignore if you don't know what this means.
options passed to editor when beginning a new puff.
options passed to editor when replying to a puff.
these should be set to filters which are activated by the corresponding number key.
disable presence notifications.
macro to run when new puff is received.
on startup, run this macro.
when replying to a puff, keep these keywords intact.
number of puffs to store in the pufflog.
maximum number of puffs to keep in memory (or 0 for no limit).
before sending a puff, get rid of leading and trailing blank lines.
set the editor. This overrides the environment.
use the default colors of your terminal if possible.
format string to use in puff display

Changing Keybindings

keys may be rebound with the 'bind' keyword in the configuration file. the syntax is

bind <key> <command>

here are some examples:

bind <C-r> reconnect_to_servers
bind c prompt_new_filter
bind v goto_match

Changing Application Hooks

When puff bodies match regular expressions, the user may choose to run arbitrary commands based on them. This can be used to follow web links in puffs for instance. The 'apphook' mechanism is fully configurable via using 'apphook' lines in your ginsu.config file.

The general form is:

apphook <name>
        <regular expression>
        <command to run>
        [string user sees in menu ("$0" by default)]
in the command and menu string, $0 is replaced by the whole regex match and $1, $2, .. $9 are replaced by the substrings captured by parenthesis in the regular expression.

apphook WikiWord
        '$BROWSER ''$2'''

apphook URL
        '$BROWSER ''$0'''

Category Aliases

Ginsu uses the same alias mechanism as 'gsend'. Aliases take the form of symbolic links in the aliases directory in the gale directory.

Here is an example of how to create new aliases.

mkdir ~/.gale/aliases  # only if it does not already exist
cd ~/.gale/aliases
ln -s pub
ln -s ugcs

Files ginsu uses

$GALE_DIR is ~/.gale/ by default.

main configuration file.
pufflog version n
main configuration file.
This is where ginsu looks for private keys for decoding incoming encrypted puffs.
This is where ginsu looks for and stores public keys.

Other ginsu resources

There is also a public arch repository for ginsu at