BASHRUN2(1)

📦
version 0.2.6 · 2 versions
, in nixos 26.05

💖 NAME 💖

okay bestie, welcome to the BASHRUN2(1) manual page — bashrun2 — and its whole vibe is: launch applications from interactive bash sessions. slay. 💅✨

🦋 SYNOPSIS 🦋

bashrun2 [options] [command [args]] [-- termopts]

🌸 DESCRIPTION 🌸

So bashrun2 adds application launching capabilities to interactive bash sessions, and it’s very much suitable for use in a graphical user environment. 💖

In its default setup, bashrun2 gives you an application launcher like a simple run dialog by starting an interactive bash session in a small xterm(1) terminal window — that’s the builtin run-dialog mode. 🎀

The builtin terminal mode starts an interactive bash session in a regular xterm(1) terminal window and transparently adds bashrun’s application launching capabilities, allowing the user to seamlessly launch graphical and terminal applications from the command line. ✨

An existing bashrun session may also be used remotely from any interactive bash session by sourcing a lightweight remote interface. 🦋

🎀 GETTING STARTED 🎀

💅 Using bashrun as a run dialog 💅

Start bashrun2 from the command line or with a keybinding in your window manager or desktop environment. Bashrun will start in its default mode run-dialog. It will create an interactive bash session in a small one-line xterm(1) terminal and initialize the bashrun engine. no cap, that’s the whole setup. 🔥

Type a command to launch a graphical application and press Enter. Bashrun will launch the application and then hide the terminal window. Now run bashrun2 again. The terminal window will be shown again and you can enter another command. This time, type the name of a console application. To launch it in a terminal, press Alt-Enter. 💖

Bring up bashrun again and press F1 to view a complete list of keybindings and available actions. 👑

🌈 Using bashrun in a managed terminal 🌈

Start bashrun with bashrun2 --mode terminal. It will launch a bashrun session in terminal mode, creating a standard sized terminal window. ✨

Pressing Enter will run commands in the current shell as usual. You can launch applications in the background now by pressing Alt-Enter. To launch a console application in a new terminal, press Alt-t. All other keybindings remain the same as in run-dialog mode. 🦋

Bind a key in your window manager or desktop environment to run bashrun2 --mode terminal and use it to bring the window up front at any time, regardless of whether it is behind other windows or on another desktop. Run bashrun2 --help or see COMMAND LINE INTERFACE for a list of available options and commands. 🫶

Use terminal mode if you want to use a dedicated, bashrun augmented terminal that can be brought up front with a single keybinding in your window manager or desktop environment. periodt. 💅

🧚 Using bashrun remotely 🧚

In an interactive bash session not started by bashrun, run the command:

eval "$(bashrun2 --remote-control)"

A lightweight remote interface to an existing bashrun run-dialog session will be installed in the current bash session. Bashrun’s keybindings will be enabled in a similar way as in terminal mode, i.e. Alt-Enter can be used to launch commands in the background, and Alt-t can be used to launch commands in a terminal. Non-executable commands will also be passed on to the remote bashrun session, providing access to handler processing. Bookmarks and handler completion will be available as well. 🌸

Use this method if you want transparent remote access to bashrun’s features from any terminal. 💜

🍓 Configuring bashrun 🍓

To configure bashrun, either edit the system wide configuration /nix/store/fjkgylim5ic414ic812kdhmjj2ihyvsx-bashrun2-0.2.6/etc/xdg/bashrun2/bashrun2.rc or create the directory ~/.config/bashrun2/ and copy the configuration file into this directory. The default configuration file contains extensivly commented examples that should help to get you started. After editing the configuration file, either restart bashrun or bring it up and press Alt-r to make changes take effect. See CONFIGURATION for further details. 🎀

💀 COMMAND LINE INTERFACE 💀

The bashrun2 executable provides a command line interface to bashrun sessions and can be used to create, select and control bashrun sessions running in different modes. It can manage a single bashrun session for each mode object defined in the configuration file. 🦋

Modes are selected by the -m or --mode option. If no mode is specified, the default mode run-dialog is used. ✨

If no session is currently running in the selected mode, then a session is started in the selected mode, unless the command is either exit or quit. The command is then applied to the newly created session, unless it is either show, toggle, smart, reload, restart or debug. If no command is specified, the default command show is used. 👑

✨ OPTIONS ✨

  • -m, --mode mode — Select mode to launch or control. In the absence of this option, the default mode run-dialog is used. 🎀
  • --remote-control — Print bash code to install a remote control interface to an existing bashrun session. See REMOTE CONTROL INTERFACE. 🦋
  • -d, --debug — Enable debugging on startup. 🔥
  • -h, --help — Show usage information. 💖
  • -v, --version — Show version information. 🌸

🌟 COMMANDS 🌟

  • show — Show the terminal window. Maps the window, moves it to the current desktop, moves it above other windows and focuses it. This is the default command if no command has been specified. 💅
  • hide — Unmap the terminal window. 🙈
  • toggle — If the terminal window is not mapped, show it. If the terminal window is mapped, hide it. 🎀
  • smart — If the terminal window is not mapped, not on the current desktop, obscured by other windows or not focused, then show it. If none of these conditions apply, hide the terminal window. ✨
  • do action [shell-command] — Remotely invoke action with shell-command. If the requested action involves su(1), the terminal window is shown before invoking the action to allow the user to enter a password. 🔐
  • su shell-command — Remotely invoke the su-run action with shell-command. This is the equivalent to do su-run shell-command. 💖
  • wid — Report the window id of the terminal window. 🪟
  • pid — Report the process id of the bash session. 🧚
  • debug — Toggle debugging. 💀
  • reload — Reload configuration files. 🦋
  • restart — Exit the bashrun session and start a new one. 🔁
  • exit — Exit the bashrun session. 👋
  • quit — Synonymous with exit. 💜

🌈 CONFIGURATION 🌈

🗂️ FILES 🗂️

Bashrun2 follows the XDG Base Directory Specification to locate configuration files. If the environment variables XDG_CONFIG_DIRS and XDG_CONFIG_HOME have not been set, are empty or include only the default directories defined by the xdg spec, then the main configuration file will be searched for at the following locations:

~/.config/bashrun2/bashrun2.rc
/etc/xdg/bashrun2/bashrun2.rc

🧁 SYNTAX 🧁

Configuration files are bash scripts that will be sourced during the startup of the bashrun session. These scripts are responsible for defining the configuration functions that contain actual object definitions as well as additional helper function definitions for a specific type of object. 🍓

For each object type, bashrun will look for a function named:

+configure-<type>s

For example, mode objects are configured by a function named:

+configure-modes

An object definition consists of an object initializer, optionally followed by one or more object property definitions on the same line, followed by one or more single object property definitions on subsequent lines:

+<type> '<name>' [--<property-name> '<args>'...]
       [--<property-name> '<args>'...]
       ...

For example, adding the following terminal object definition to the +configure-terminals function will create a new terminal object called small and set its command and geometry properties:

+terminal 'small'
  --command 'urxvt'
  --geometry '40x12'

Note that if an object initializer refers to a previously defined object of the same type using the same name, then subsequent property definitions will apply to the existing objects instead of creating a new object, i.e. the above example could also be written as:

+terminal 'small' --command 'urxvt'
+terminal 'small' --geometry '40x12'

Multiple arguments to property definitions are usually concatenated into a single string separated by spaces, unless otherwise indicated. ✨

💅 KEYBINDINGS 💅

The configuration functions +configure-emacs-mode and +configure-vi-mode are used to configure keybindings for the respective editing modes. Within these functions, the following directives may be used:

  • +keymap <keymap> — Set the target keymap for subsequent bind directives. 🎀
  • +bind <action> <keyseq> [<keyname>] — Bind an action to a key sequence, optionally supplying a human readable key name. See readline(1) on how to specify key bindings. 🦋
  • +unbind <action> [<keyseq>] — Unbind an action from a key sequence. If the key sequence is omitted, the action will be unbound from the last key sequence that was previously bound to. If a key sequence was bound to a readline function or macro prior to having been bound to a bashrun action, the original readline binding will be restored. E.g. unbinding the run action from \C-m (enter) will automatically rebind \C-m to readline’s accept-line function. 💖
  • +rebind <action> — Rebind the action to the key sequence that it was previously bound to, if any. 🔁

🧚 PLUGINS 🧚

The +plugins directive can be used to include one or more named plugins into the main configuration file, and must appear at the top level of the configuration file, i.e. outside of any +configure function. A plugin may contain additional object definitions that will be added to the objects defined by the main configuration file. The plugin files will be searched for in the following locations:

~/.config/bashrun2/plugins/<plugin-name>.rc
/etc/xdg/bashrun2/plugins/<plugin-name>.rc

For each object type, a plugin may define a +configure function using the following naming scheme:

+configure-<plugin-name>-<type>s

Configuration functions provided by plugins will be run before those defined in the main configuration file. 🫶

🔥 CACHING 🔥

The results of a specific +configure function are cached in XDG_CACHE_HOME/bashrun2. Objects of the corresponding type and associated helper functions will be restored from the cache on subsequent invocations, until the code of the +configure function changes, upon which the function is again run and the resulting objects and functions are again cached to replace the previously cached results. iykyk. 💜

🧸 OBJECTS 🧸

okay so bestie, this is where bashrun shows off its whole “made of little configurable friends” era 💅 — it's composed out of a set of user configurable objects that control different aspects of application launching and terminal window management. Like a group chat, but every member has a job.

  • Modes — control the appearance and behavior of the terminal hosting the bashrun session, such as the default modes run-dialog and terminal mentioned above.
  • Actions — can be bound to key sequences and handle user input in different ways, such as launching a command in a terminal or looking up words in a dictionary client.
  • Terminals — let you specify different terminal command lines to be used for launching console applications, and can be associated with specific commands or command lines.
  • Rules — associate actions with specific commands or command lines, e.g. to automatically launch certain commands with root privileges. Regular expressions allow fine grained control over command matching.
  • Handlers — provide a flexible mechanism for rewriting non-executable commands, using regular expression matching, substitution and file test operators, thus offering a way to implement stuff like file associations or web shortcuts. They also provide a simple interface to programmable completion.
  • Plugins — allow flexible inclusion and distribution of user created configuration objects.

🦋 MODES 🦋

Mode objects are used to configure different modes of operation for bashrun. They define the terminal to use for the bashrun session and control general appearance and behavior. Basically the main-character settings for how your little launcher looks and acts ✨

  • --terminal <name> — default: xterm. The terminal used for bashrun. Supported terminals include xterm, urxvt, urxvtc, urxvtcd, mrxvt, mlterm and aterm. Generic support for other terminals can be added as well, see GENERIC TERMINAL SUPPORT below.
  • --geometry <geometry1 [geometry2]...> — default: 40x1 40x8. The geometry or geometries to use for the terminal window. If more than one geometry is used, the cycle-size action (Ctrl+l) will allow you to cycle through these geometries.
  • --font <font> — default: empty. The regular terminal font.
  • --boldfont <font> — default: empty. The bold terminal font.
  • --foreground <font> — default: empty. The terminal foreground color.
  • --background <font> — default: empty. The terminal background color.
  • --options <string> — default: empty. Generic terminal options to be included in the terminal command line.
  • --completion <type [alternative threshold]> — default: menu-complete complete 8. Set the readline completion function to use with tab. type specifies the completion type to be used by default. alternative, if given, specifies an alternative completion type to use when the size of the terminal is greater or equal to the number of lines given in threshold. Possible values for type and alternative are the default readline types complete and menu-complete, as well as the special quiet-complete type. This type will behave like the standard complete, but will not prompt the user in any way, so that although possible completions will be listed, they will effectively not be visible in a single-line terminal.
  • --cmdnfh <boolean> — default: true. Install a command_not_found_handle function that will pass the command to the run action and thus invoke handler processing. The handler function will only be invoked if the command is entered using readline's accept-line function.
  • --unmap <boolean> — default: true. Unmap (hide) the terminal window after every command.
  • --onmap <command> — default: empty. A command to be run after the terminal window has been mapped.
  • --onunmap <command> — default: empty. A command to be run after the terminal window has been unmapped.
  • --netwmstate <string> — default: empty. A space separated list of NetWM state properties to apply to the window when it is shown. Possible values are modal, sticky, maximized_vert, maximized_horz, shaded, skip_taskbar, skip_pager, hidden, fullscreen, above and below. Note that your wm needs to properly support these properties in order for them to have any effect. It is usually better to use your wm's native facilities to set such properties.
  • --feedback <boolean> — default: true. Show feedback in the form of a progress bar when creating/restoring the configuration.
  • --superuser <string> — default: Administrator. Set the name of the superuser to use for su-* actions when running under cygwin.
  • --logfile <filename> — default: /dev/null. Redirect stderr from launched commands to filename. Note that stderr for commands run with root priviledges is discarded by default.
  • +mode-<name>-init () { commands; } — a function that will be run when the corresponding mode to is initialized. This is a good place to refine the default setup or to set bash settings such as PS1 or HISTFILE for a specific mode.

🎀 TERMINALS 🎀

Terminal objects define different terminal command lines to use for launching commands in. Commands can be matched and associated with a specific terminal objects using the --match property. It's giving “choose your fighter” but for terminal emulators 💖

  • --command <command template> — default: xterm. The terminal command. Supported terminals include xterm, urxvt, mrxvt, mlterm and aterm. Generic support for other terminals can be added as well, see GENERIC TERMINAL SUPPORT below.
  • --geometry <geometry> — default: empty. The X geometry of the terminal.
  • --font <font> — default: empty. The regular terminal font.
  • --boldfont <font> — default: empty. The bold terminal font.
  • --foreground <font> — default: empty. The terminal foreground color.
  • --background <font> — default: empty. The terminal background color.
  • --classname <string> — default: none. Name portion of the WM_CLASS window property.
  • --title <string> — default: none. Title of the terminal window.

If not specified, the command executed in this terminal will be used as the window title.

  • --options <string> — default: empty. Generic terminal options to be included in the terminal command line.
  • --match <pattern> [...] — default: empty. Add one or more patterns to match commands or command lines with. If an action requests the command to be run in a terminal, then if the pattern matches, this terminal is chosen to run the command in.

If pattern is a single word, it will be matched verbatim against the first word of the command line. If the pattern is delimited by slashes (i.e. /pattern/), then the pattern is matched as a regular expression on the complete command line. Note that slashes inside the regular expression do not have to be escaped with a backslash in this notation.

There are two terminal objects defined by default. The terminal named default will be used if no other terminal matches the given command and an action has requested the command to be run in a terminal. The default notify terminal is a small terminal used by the default actions term-notify and su-term-notify (see DEFAULT ACTIONS below).

⚠️ Note that any patterns associated with a terminal object will be implicitly appended to the term-run rule (see RULES below). This means that commands matched by a terminal will always be run in that terminal, even if this was not explicitly requested by the current action.

💫 Icon support for terminal windows 💫

On startup, if either $HOME/.config/bashrun2/icons or $SYSCONFDIR/xdg/bashrun2/icons exists, bashrun will add an X resource for each .png file found in these directories, in the format

<basename-of-icon>*iconFile: <full-path-of-icon>

In addition, every time a command is launched in the terminal, bashrun will attempt to load an icon resource in the same manner, based on the first word on the commandline or the explicitly set terminal title.

Icons from the users configuration directory take precedence over those found in the system-wide configuration directory. So your personal icon stash wins, periodt 🫶

🌸 BOOKMARKS 🌸

For each bookmark object, a stub function by the same name is defined that runs the browse action for the bookmark name. Bookmarks can thus be completed like regular commands. Example:

+bookmark 'www.google.com'

🔥 RULES 🔥

Rule objects associate actions with specific commands or command lines. The rule name must correspond to the name of an existing action. The first rule that matches the command will take effect and invoke the corresponding action on the command. Rule processing takes place only if the generic run action is invoked on the command. No cap, first match wins 💅

  • --match <pattern> [...] — default: empty. Add one or more patterns to match commands or command lines against.

If pattern is a single word, it will be matched verbatim against the first word of the command line. If the pattern is delimited by slashes (i.e. /pattern/), then the pattern is matched as a regular expression on the complete command line. Note that slashes inside the regular expression do not have to be escaped with a backslash in this notation.

🧚 HANDLERS 🧚

Handler objects can be used to match, test against and rewrite non-executable command lines and then either execute the resulting command or dispatch the resulting string to a specific action for further processing. In addition, handlers provide a simple interface to programmable completion. This is the “make it make sense” layer 🔥

If the commandline entered into bashrun is not executable (i.e. it's not an exported function, an alias or an executable) then an attempt is made to successively match the command line against each of handlers, in the order in which they are defined in the configuration files.

If the regular expression given with --match matches the commandline, then an optional file test pattern given with --test is applied. If no test was specified or if the supplied test succeeds, then either the value of --command will be used as the command to execute, with the original command line appended, or, if the regexp contains subexpressions within parenthesis, an attempt will be made to substitute the occurence of %<1-9> in the value of --command with the contents of the corresponding subexpression match.

The --action property may be used to delegate the resulting string to a specific action for further processing. If no action was given, the resulting string is assumed to constitute an executable command, and will be run in the background. Slay, but make sure you meant it 😭

A command word to complete can be totally supplied via the --complete property, and you can define a function named +handler-<name>-complete to generate a list of possible completions. ✨

  • --match <regexp> (default: (.+)) — the regular expression to match against the command line. The results of any matching parenthesized subexpressions inside this expression can be inserted into the --command template (peep --command below).
  • --test <expression> (default: empty) — the test expression is a string of characters that line up with the unary file test operators defined in section CONDITIONAL EXPRESSIONS of the bash(1) manual. Each individual file test gets performed on the complete command line. If one of these tests fails, the test as a whole fails and the handler is skipped. File tests can be negated by prefixing them with a single !. For example, a handler using the expression f!x will only be applied if the command line constitutes the filename of a regular, non-executable file.
  • --command <command template> (default: empty) — the command template rewrites the original command line to construct an executable command line or a string that can be passed on to an action for further processing, denoted by the --action property. If the template contains a percent sign (%) followed by a single digit in the range 1-9, then this pattern will be replaced with the matching contents of the corresponding parenthesized subexpressions in the regular expression given with --match. If no such patterns occur in the command template, then the original command line is appended to the end of the template string, separated by a space character.
  • --action <name> (default: empty) — the name of an action that shall be invoked on the rewritten command string. If no action is specified, the rewritten command string is assumed to constitute an executable command and is executed in the background.
  • --complete <word> (default: empty) — a stub function word is created and can thus be completed on the command line. Standard bash completion is installed for this word unless a specific completion function is supplied for this handler (see below).
  • --fallback <boolean> (default: false) — if set to true, this handler will always appear at the end of the handler chain, regardless of where it was defined in the configuration files. If more than one fallback handler is defined, they will end up at the end of the handler chain in the order in which they are defined in the configuration files.
  • +handler-<name>-complete () { commands; } — an optional function that generates a newline-separated list of possible completions used for the word given by the --complete property of the corresponding handler. If no such function is defined, standard bash completion will instead be installed for the word. 🫶

🎬 ACTIONS 🎬

Action objects implement the core functionality of bashrun by handling user input in arbitrarily complex ways. Actions can be invoked directly by the user via key bindings or remotely from the command line. Each action is augmented by an associated helper function which is responsible for generating an executable command based on user input. To do so, an action function can interact with the bashrun engine by using special functions — e.g. to get or set the resulting command, test it for certain conditions, invoke handler and rules processing, add a terminal, change the effective user id, or simply run some shell commands and then terminate processing. See the description of the +action-<name> function below for details. 💖

  • --description <string> (default: empty) — a short description for this action. This string will be used to describe the action to the user when listing key bindings.
  • --depends <list> (default: empty) — a space separated list of external programs used by this action. The user will be prompted with an appropriate error message if one of these dependencies is not satisfied.
  • --input <boolean> (default: true) — accept the current line as input for this action. If set to false, the action will be invoked without altering the current line.
  • --remote <boolean> (default: true) — include this action in the remote control interface. (See REMOTE CONTROL INTERFACE.)
  • +action-<name> () { commands; } — the function implementing this action. The return value of this function determines how to proceed further:
    • returns 0 → bashrun assumes that the current command set by the command function (see below) is executable and will proceed to spawn a new instance of bash to execute the command.
    • returns 1 → the action terminates immediately, possibly unmapping the terminal window if requested by the +mode --unmap property.
    • returns 2 → the action terminates without ever unmapping the terminal window, ignoring the value of +mode --unmap.

The following functions are defined during execution of the action function:

  • command [value] — get or set the command. If no value is given, print the current command on stdout. If a value is given, set the current command to value.
  • line — print the complete command line entered by the user to stdout.
  • word — print the first word of the command line entered by the user to stdout. Note that any environment variable assignments at the beginning of the line will be skipped when determining the command word.
  • title — set the title to be used in case this command is run in a terminal. Note that this command must be called before the terminal command line is constructed, i.e. before terminal, pager or hold is called.
  • quote-command — quote the command in a way that can be reused as shell input.
  • action <name> — run the action function of the action denoted by name on the current command.
  • handlers — invoke handler processing for the command.
  • rules — invoke rules processing for the command.
  • terminal [<name>] — modify the command to be run in the terminal specified by name. If no explicit terminal name is given, then the terminal that matches the command will be used. If no terminal matches the command or no terminal of the given name exists, the default terminal is used.
  • hold [<sec=0>] — modify the command to add a delay of sec seconds after the command has been run. If sec is 0 (the default), wait until the user presses a key.
  • pager — modify the command to page the output in a pager. The value of the environment variable PAGER (default: less) will be used for this.
  • user [--prompt] [<username=root>] — modify the command to be run with a different user id by using su(1). If the --prompt option is supplied, prompt the user for the username; otherwise use the supplied username (default: root). The terminal window will be mapped prior to running the command to allow the user to enter the username and/or password.
  • map — map the terminal window, e.g. to prompt the user.
  • executable? — test whether the command is executable.
  • builtin? — test whether the command is a bash builtin command.
  • bookmark? — test whether the command is a bashrun bookmark.

👑 BUILTIN ACTIONS 👑

This section describes the default actions defined in bashrun, along with their default keybindings. 🌈

If you wish to change the implementation of a default action, enter debug mode, type +action <name> --code and press M-w to retrieve the source code of the action. You can add this code to your +configure-actions function in your configuration file and modify it accordingly. 💅

  • pass (M-w) — run a command directly in the bashrun shell session.
  • abort (C-g) — clear the command line and hide the terminal window.
  • bashrun-bindings (F1) — show the current keybindings in a terminal.
  • bashrun-manual (F2) — show this manual page in a terminal.
  • debug (F12) — resize the terminal window to 80x24 and turn on debugging.
  • reload (M-r) — reload the configuration. All configuration objects are reloaded from the cache unless a configuration function for a certain type of object has changed.
  • quit (C-q) — terminate the bashrun session.
  • run (C-m, C-j, Enter) — run a command as an independent process, detached from the bashrun shell session. If the command is not executable, try match it against handlers. If no handlers match, abort processing, else apply rules and proceed. This behaviour is common for all run-* actions.
  • term-run (M-C-m, M-Enter) — run the command in a terminal.
  • term-hold (M-h) — run the command in a terminal and keep the terminal open until the user presses any key.
  • term-page (M-+) — run the command in a terminal and display the output using the pager program defined by the environment variable PAGER. If this variable is unset or empty, use less(1).
  • term-notify — run command in the default notify terminal and hold for two seconds.
  • su-run (M-su) — run a command as root. Will prompt the user for the root password.
  • su-term-run (M-st) — run the command as root in a terminal.
  • su-term-hold (M-sh) — run the command as root in a terminal and keep the terminal open until the user presses any key.
  • su-term-page (M-s+) — run the command as root in a terminal and display the output using the pager program defined by the environment variable PAGER. If this variable is unset or empty, use less(1).
  • su-term-notify — run command as root in the default notify terminal and keep the terminal open for two seconds.
  • show-manual (M-?) — show the manual page for a command.
  • show-info (M-C-?) — show the manual page for a command.
  • show-help (M-C-x?) — show help for a bash builtin.
  • browse (M-C-b) — launch urls in $BROWSER.
  • google-search (M-C-g) — use command line contents as a search term on google.
  • dict-lookup (M-C-d) — lookup words in a dictionary client. ($DICT)
  • copy-to-clipboard (M-x) — copy command output to clipboard using xclip -i. 🎀
  • filter-clipboard (M-a) — use command as a filter on the clipboard. It’s literally equivalent to this tiny pipeline:
xclip -o | command | xclip -i
  • cycle-size (C-l) — cycle through the geometries given by +mode --geometry. ✨
  • resize-up (C-↑) — decrease terminal height by one line.
  • resize-down (C-↓) — increase terminal height by one line.
  • resize-left (C-←) — decrease terminal width by one column.
  • resize-right (C-→) — increase terminal width by one column.

✨ GENERIC TERMINAL SUPPORT ✨

Generic support for terminals can be added by supplying a template string of the required terminal command line to the +mode --terminal or +terminal --command properties. 💅

Template strings may contain the following format specifiers, which will be replaced by their corresponding values:

  • %* — the command to be run by the terminal, unquoted.
  • %@ — the command to be run by the terminal, quoted to appear as a single argument. Consecutive @’s add another level of quoting, e.g. %@@ quotes two times, %@@@ quotes three times, and so on.
  • %n — for +mode objects, this is replaced with the string bashrun2-<mode-name>, and needs to be set as the name portion of the terminal’s WM_CLASS property. For terminal objects, the value of the --classname property is used.
  • %g — the value of the --geometry property.
  • %f — the value of the --font property.
  • %b — the value of the --boldfont property.
  • %F — the value of the --foreground property.
  • %B — the value of the --background property.
  • %o — the value of the --options property plus any additional terminal options given on the command line after --.
  • %% — replaced by a literal percent sign (%).
🫶 Heads up, bestie: any format specifier that appears in the template string will always be replaced with its corresponding value, even if the value is an empty string. So make sure that format specifiers whose value is derived from an option are not empty (e.g. the corresponding option is set), or you’ll be constructing an invalid command line. No cap.

Examples:

+mode

--terminal 'urxvt -n %n -g %g -fn %f -fb %b -fg %F -bg %B %o -e %*'

+terminal

--command 'urxvt -n %n -g %g -fn %f -fb %b -fg %F -bg %B %o -e bash -c %@'

💀 KNOWN ISSUES 💀

Older versions of bash may freeze when resizing the terminal window, and will need to be forcefully terminated in this case. 😭

For XTerm, the allowWindowOps resource needs to be set to True to allow window resizing. This is enabled by default. 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. When using XTerm, bashrun will set this resource to True by default. For URxvt, the meta8 resource needs to be set to False (which is already the default setting in URxvt).

📁 FILES 📁

  • /etc/xdg/bashrun2/bashrun2.rc — system-wide configuration file
  • /etc/xdg/bashrun2/plugins/ — system-wide plugin directory
  • $HOME/.config/bashrun2/bashrun2.rc — user configuration file
  • $HOME/.config/bashrun2/plugins/ — user plugin directory
  • /nix/store/fjkgylim5ic414ic812kdhmjj2ihyvsx-bashrun2-0.2.6/bin/brwctl — small utilty program for window management

🐛 BUGS AND FEEDBACK 🐛

Please file bugs and feature requests on the GitHub issue tracker:

https://github.com/hbekel/bashrun2/issues

Also feel free to mail me directly using the email adress below. Questions, comments, suggestions, feedback of any kind is greatly appreciated. 💖

👑 AUTHOR 👑

Henning Liebenau <henning dot liebenau at protonmail dot com>

🔗 SEE ALSO 🔗

bash(1) readline(3) xterm(1) su(1) stty(1)

Okay that’s the whole page, bestie 🫶 — source/version Linux, dated 2020-12-15, and it’s BASHRUN2(1). Mwah 💋✨

📦 where this page comes from