bashrun provides two basic modes of operation, depending on whether xdotool(1) is installed on the system.
If xdotool(1) is available, the terminal hosting the bash session will be kept running in the background, hidden from display. Invoking bashrun or bashrun --show will show and focus the window; after issuing a command, the terminal window will be hidden from display again. This method reduces startup time and saves system resources.
If xdotool(1) is not installed, a new instance is created on each invocation, immediately terminating after running the first command.
If xdotool(1) is available, the following options control a running bashrun instance from subsequent invocations. Note that if no previous bashrun instance is found, options --show, --toggle, --restart, --su and --debug will start a new bashrun session.
toggle debug mode
- --show
- map the window and focus it
- --hide
- unmap the window
- --toggle
- toggle window visibility
- --exit
- terminate an existing bashrun process
- --restart
- restart bashrun (required to apply configuration file changes)
- --su command
- run command with root privileges. Brings up the bashrun terminal for password entry.
- --remote type <text> key <keyseq> ...
- Type text into bashrun and invoke key sequences remotely. See the key command in xdotool(1) for the syntax of <keyseq>.
- --wid
- print the terminal’s window id
- --wait
- wait until terminal window is unmapped
- --debug
Multiple commands separated by ; are successively handled in the same manner.
If commands are separated by a pipe symbol (|) or by the logical operators || or && then bashrun’s behavior will substantially differ from the normal shell behavior. To the bashrun shell, every simple command in a compound statement will appear as though it immediately returns success. This means that separating commands with && or | is effectively equivalent to using ;. Separating commands with || will prevent the execution of commands on the right hand side of the expression.
To circumvent this behavior, the characters ;, & and | can be escaped with a backslash character (\). Please note that in this case terminal rules are only applied based on the command name of the first command.
To illustrate, a command like
$ cat textfile | wc -l <term-page>
will fail to work as intended and instead page the output of both commands in separate terminals, with no pipe established between the commands. You
will need to use
$ cat textfile \| wc -l <term-page>
to page the number of lines in textfile in a single terminal window as intended.
Editing multiple lines does not work in bashrun. If you happen to forget a closing quote on your commandline, bashrun will ask you to press C-c. Your last history line may be bogus after this.
To run commands in the context of the bashrun shell session instead of having them handled by bashrun, use the <pass> action (default: M-w).
The keymap directive chooses the readline keymap that subsequent keybinding definitions will be bound to. The syntax is
KEYMAP <keymap>
where <keymap> is either emacs, vi-insert or vi-command.
The syntax for keybinding
definitions is
<action> <keyseq> [<keyname>]
where <action> is the name of the bashrun action (see ACTIONS below), keyseq is a valid readline(1) key sequence, and <keyname> is an optional human-readable name for the key sequence (used to display the keybindings to the user).
Please note that all key sequences beginning with C-x[0-9] as well as the literal characters \\201 up to \\209 are reserved for internal use and can not be used.
Lines beginning with # are comments and will be ignored.
Please make sure that you don’t interfere with the tty/bash settings and reserved keybindings used by bashrun. See KEYBOARD CONFIGURATION FILE and ENVIRONMENT or take a look at $PREFIX/share/bashrun/bashrc.
XTERM=[xterm|rxvt|urxvt|urxvtc|mrxvt|aterm|mlterm] (default: xterm)
The terminal to be used for bashrun.
XTERM_OPTIONS=[...] (default: empty)
Additional commandline options to be passed to the terminal.
KEEP_OPEN=[yes|no] (default: no)
If set to "yes", the terminal won’t be hidden after every command. Subsequent invocations of bashrun or bashrun --show will focus the terminal window, <abort> or bashrun --hide will unfocus the window and give focus back to the previously focused application.
SMALL_COLUMNS=n, SMALL_LINES=n (default: 40x1)
Size of the terminal in the default "small" mode.
LARGE_COLUMNS=n, LARGE_LINES=n (default: 40x8)
Size of the terminal in "large" mode, toggled via <toggle-size> (xterm and *rxvt only).
FGCOLOR=color, BGCOLOR=color (default: grey on black)
Foreground and background color of the terminal. Consult your terminal’s documentation for possible values.
PS1=[...] (default: ’>’)
Prompt string, see bash(1)
HISTCONTROL (default: ignoredups:erasedups)
History settings, see bash(1)
COMPLETION_TYPE=[complete|menu-complete|quiet-complete] (default: menu-complete)
For complete and menu-complete, see bash(1). The quiet-complete mode will use complete and additionally set the following readline variables:page-completions off
print-completions-horizontally on
completion-query-items -1
The quiet-complete mode is useful if you want completion to behave like complete but without being interrupted by readline prompts. Although completions are actually printed you will effectively not see them in a one-line-terminal.
ALTERNATIVE_COMPLETION_TYPE=[complete|menu-complete|quiet-complete] (default: complete)
The completion type to switch to if LINES >= COMPLETION_THRESHOLD, see below.
COMPLETION_THRESHOLD=[num_lines] (default: LARGE_LINES)
If the number of LINES in the terminal is equal or greater than this value, switch to ALTERNATIVE_COMPLETION_TYPE. If the value is less than 1, this feature is disabled.
(Note: the default setup for these options results in using menu-complete in "small" mode and complete in "large" mode.)
USE_EXTENDED_BASH_COMPLETION=[yes|no] (default: no)
Whether to use extended bash completion.
EXTENDED_BASH_COMPLETION_PATH=[path]
(default: /etc/profile.d/bash_completion.sh) Path to a script enabling extended bash completion. Consult your distribution’s documentation.
POST_MAP_COMMAND=[command] (default: not set)
Command to run directly after making the window visible via xdotool. E.g. you could set the transparency of the window to 75% using transset -a 0.75 when running xcompmgr.
DICT_CLIENT=[command] (default: dict --pager $PAGER)
Which dict client to use for the <dict-lookup> action. Add your client to the TERMINAL_RULES if neccessary.
DIRHANDLER=[command] (default: not set)
A command to be run when a path to a directory is entered and the directory is readable. The path will be passed as the first argument to the specified command.
BROWSER=[command] (default: firefox)
Browser to use for google search and default handlers (see below).
GOOGLE_FALLBACK=[yes|no] (default: no)
If set to yes bashrun will automatically google the commandline if it isn’t executable or if it’s not handled by HANDLERS or DIRHANDLER
TERMINAL_RULES=(’RUN:[progs]’ ’PAGE:[progs]’ ’HOLD:[progs]’)
An array containing rule strings that define which programs should always be launched in a terminal window. Insert a space separated list of program names after the : into the string for the desired rule. Programs in the RUN rule are always launched in a terminal. Programs in the PAGE rule will have their output paged in PAGER. For programs in the HOLD rule the terminal is kept open after the program terminates.Example:
TERMINAL_RULES=(
"RUN:watch top htop less man info ncftp links"
"HOLD:ps su"
"PAGE:echo ls which uname lsusb lshal lsmod fortune"
)
HANDLERS=([regexp handler]...) (defaults: see below)
An array containing bash regular expressions and associated handler strings. If the commandline entered into bashrun is not executable (i.e. it’s not a function, alias or a binary on PATH) then an attempt is made to successively match the commandline against the patterns contained in HANDLERS. If a pattern matches, either the handler string following the pattern will be used as the command to execute, with the commandline itself passed as the argument, or, if the regexp contains subpatterns within parenthesis, an attempt is made to substitute the occurrence of $[1-9] in the handler string with the contents of the corresponding subpattern match. The modified handler string is then used as the commandline without adding further arguments.If there are not enough subpattern matches to substitute every occurrence of $[0-9] in the handler string then the handler will not be executed and an error message will be issued to the user.
The handler string may additionally be prefixed with a file test expression defining a series of file tests to be performed on the contents of the commandline prior to applying the handler. If any of these tests fail, the handler will not be applied.
The test expression is a series of characters corresponding to the unary file test operators defined in section CONDITIONAL EXPRESSIONS of the bash(1) manual, terminated by :. File tests can be negated by prefixing them with a single !. E.g. a handler prefixed with f!x: will only be applied if the commandline is a path to a regular, non-executable file.
For example, to define file associations
for jpeg files you can use a pattern and handler like
’\.jpe?g$’ ’f!x:gimp’
This will open lines ending in .jpg or .jpeg using gimp(1). The file test
ensures that you can still type a line like
$ convert foo.tif foo.jpg
which will not be handled although it also ends in .jpg. This is because the test expression is applied to the complete line, so the f!x test will fail.
To open lines beginning with http or https in your BROWSER, add a line like this to the HANDLERS array:
’^https?’ "$BROWSER"
To implement web shortcuts similar to KDE’s konqueror browser, use a pattern containing a subpattern, like this:
’^gg:(.+)’
and use a line like this as the handler string:
"$BROWSER ’http://www.google.com/search?q=\$1’"
Bashrun will replace the $1 part of the handler string with anything the user has entered after gg:.
See the default user configuration file for more examples. if your handlers don’t work as expected, turn on debug mode to see what is going on.
The following handlers are setup by default if the default configuration file is being used or HANDLERS is not set in the user configuration file:
Show man $1 in xterm
- ^www, ^https?
- Open lines beginning with www, http or https in BROWSER
- ^gg:(.+)
- ^ggl:(.+)
- Google using "I’m feeling lucky"
- ^fm:(.+)
- Search for project on freshmeat.net
- ^sf:(.+)
- Visit project page on sourceforge.net
- ^sfw:(.+)
- Visit project website on sourceforge.net
- \.jpe?g$
- Open JPEG files in gimp, using f!x as test expression
- ^ftp:(.+)
- Start ncftp $1 in xterm
- ^\?(.+)
- Page $1 --help in xterm
- ^\?\?(.+)
BOOKMARKS=([bookmark]...) (default: see example)
An array of strings that will be added to the possible command completions. Make sure there is a handler defined in HANDLERS for each of the strings used as bookmarks. Example:LOGFILE=[path] (default: /dev/null)BOOKMARKS=(
www.google.com
www.archlinux.org
www.slashdot.org
www.linux.com
http://bashrun.sourceforge.net
)
Command output (stdout and stderr) is appended to LOGFILE. If it doesn’t exist, bashrun will attempt to create it. If it is not writeable, output is redirected to /dev/null instead.Logging is disabled for commands run with root privileges.
The user configuration file. If it does not exist, it will be created and initialized with the default configuration.$XDG_CONFIG_HOME/bashrun/keys
The keyboard configuration file. If it does not exist, it will be created and initialized with the default keybindings.If xdotool(1) is used, bashrun needs to be restarted to make changes to these files take effect.
If XDG_CONFIG_HOME is not set or empty, ~/.config will be used instead.
$XDG_DATA_HOME/bashrun/history
The history file used by bashrun. If XDG_DATA_HOME is not set or empty, ~/.local/share will be used instead.
$XDG_CACHE_HOME/bashrun/
Directory for temporary files created by bashrun. If XDG_CACHE_HOME is not set or empty, ~/.cache will be used instead.
The extdebug shell option is enabled. A trap on DEBUG is set each time a commandline is issued. The trap is disabled again after commandline processing to prevent it from interfering with interactive commandline editing.
Sending ^D (eof) on an empty line does not terminate the shell if xdotool(1) is being used. See stty(1)
XON/XOFF flow control (Suspend/Resume terminal via C-s and C-q) is disabled. C-s will search forward in the history buffer (readline default) while C-q is bound to the <quit> action when using the default keybindings. See stty(1)
Only xterm(1) and *rxvt(1) support resizing using keybindings. xterm has occasionally been found to freeze during resizing, requiring at least a SIGTERM to close it.
For XTerm, the allowWindowOps resource needs to be set to True to allow window resizing. This is enabled in the default configuration for xterm as of bashrun version 0.14. Note that setting allowSendEvents to True will forcefully disable allowWindowOps in XTerm.
In order for meta keybindings (prefixed with \e or \M-) to work with the Alt or Meta key, the terminal needs to be configured to translate your meta key to an escape. For XTerm, this can be enabled by setting the metaSendsEscape resource to True. This is enabled in the default configuration for xterm as of bashrun version 0.14. For URxvt, the meta8 resource needs to be set to False (which is the default setting for URxvt).
xdotool - (http://www.semicomplete.com/projects/xdotool)
dict - (http://www.dict.org/)