EVENT(1)

NAME

event - manage named shell event hook registrations.

SYNOPSIS

event add event name function [--priority number]
event add timer.tick name function --every milliseconds [--priority number]
event remove event name
event list [--json] [event]

DESCRIPTION

event registers shell functions for Rush shell events. Registrations are named. Reusing an event and name replaces that hook.

Hooks run by ascending priority, then registration name. The default priority is zero. Hooks preserve visible status unless they exit the shell.

event list prints hooks grouped by event. event list --json prints objects with event, name, function, priority, and optional every_ms.

directory.change
  direnv priority=0 rush_direnv_hook
timer.tick
  clock priority=0 every=1000ms on_clock

Hooks receive temporary RUSH_EVENT and RUSH_EVENT_HOOK assignment-prefix variables while they run.

EVENTS

directory.change: Runs after a successful current-shell directory change. Receives old directory as $1 and new directory as $2. Also runs once at interactive startup before the first prompt, with an empty $1 and the initial directory as $2.
prompt.prepare: Runs on the real interactive shell state before Rush renders each prompt.
prompt.async.start, prompt.async.end: Run when prompt async refresh work starts or ends. Receive $1=prompt and $2 as the active count.
job.start, job.end: Run when interactive background jobs become active or inactive. Receive $1=job and $2 as the active job count.
timer.tick: Runs while the line editor is idle after the registration's --every interval. Receives the registration name as $1.

EXAMPLE

sync_project_env() {
  if test -f .envrc; then
    . ./.envrc
  fi
}

remember_prompt_cwd() {
  rush_prompt_cwd="$PWD"
}

event add directory.change project-env sync_project_env --priority -10
event add prompt.prepare prompt-cwd remember_prompt_cwd
event add timer.tick clock remember_prompt_cwd --every 1000

RECIPES

Enable bundled project-environment helpers in a later config file. These helper functions are autoloaded from share/rush/functions when the hook first runs:

event add directory.change direnv rush_direnv_hook
event add directory.change mise rush_mise_hook

Replace or remove hooks by event/name:

event add directory.change direnv my_direnv_hook
event remove directory.change mise

EXIT STATUS

Zero on success and two for usage errors.