hwatch

hwatch - alternative watch command.

Description

hwatch is a alternative watch command. That records the result of command execution and can display it history and diffs.

Features

• Can keep the history when the difference, occurs and check it later.
• Can check the difference in the history. The display method can be changed in real time.
• Can output the execution result as log (json format).
• Can load diffmode plugins as dynamic libraries and add custom diff rendering.
• Custom keymaps are available.
• Support ANSI color code.
• Execution result can be scroll.
• Not only as a TUI application, but also to have the differences output as standard output.
• If a difference occurs, you can have the specified command additionally executed.

Install

macOS

# brew
brew install hwatch

# MacPorts
sudo port install hwatch

Arch Linux (AUR)

# paru
paru -S hwatch

# yay
yay -S hwatch

Nix

nix profile install nixpkgs#hwatch

Alpine Linux (edge/testing)

apk add hwatch

mise/asdf

# mise
mise use -g aqua:blacknon/hwatch

# asdf
asdf plugin add hwatch
asdf install hwatch latest
asdf global hwatch latest

Cargo Install

cargo install hwatch

Logfile Reuse

When --logfile points to an existing file, hwatch tries to read and reuse its history. If the file is empty or unreadable, interactive sessions ask for confirmation before continuing.

For non-interactive runs such as CI, scripts, and batch mode, use --force-logfile-overwrite to skip that confirmation and continue with the existing path:

hwatch --force-logfile-overwrite --logfile ./hwatch.jsonl -b -g 1 -n 0.1 sh ./script.sh

Security Notes

• --diff-plugin loads native dynamic libraries. Only load plugins you trust.
• --shell, the monitored command itself, and --aftercommand execute commands on your system. Treat those values as trusted input only.

Packaging Status

This repository includes packaging metadata for Debian-style .deb builds and RPM-based distributions.

GitHub Actions validates the packaging flow in distro-specific containers:

• Debian packaging is checked in a debian:sid container
• RPM packaging is checked in a fedora:latest container

These checks are intended to catch packaging regressions early while the project works toward official distribution packaging. Additional strict packaging jobs also run in CI on a best-effort basis to track progress toward dependency-complete distro builds.

Usage

Command

$ hwatch --help
A modern alternative to the watch command, records the differences in execution results and can check this differences at after.

Usage: hwatch [OPTIONS] [command]...

Arguments:
  [command]...

Options:
  -b, --batch
          output execution results to stdout
  -B, --beep
          beep if command has a change result
  -g, --chgexit [<chgexit>]
          exit when output changes. With no value, exits after the first change; with N, exits after N changes
      --border
          Surround each pane with a border frame
      --with-scrollbar
          When the border option is enabled, display scrollbar on the right side of watch pane.
      --mouse
          enable mouse wheel support. With this option, copying text with your terminal may be harder. Try holding the Shift key.
  -c, --color
          interpret ANSI color and style sequences
  -r, --reverse
          display text upside down.
  -C, --compress
          Compress data in memory. Note: If the output of the command is small, you may not get the desired effect.
  -t, --no-title
          hide the UI on start. Use `t` to toggle it.
      --enable-summary-char
          collect character-level diff count in summary.
  -N, --line-number
          show line number
  -w, --wrap
          disable line wrap mode
      --no-help-banner
          hide the "Display help with h key" message
      --no-summary
          disable the calculation for summary that is running behind the scenes, and disable the summary function in the first place.
      --completion <SHELL>
          Output shell completion script [possible values: bash, fish, zsh]
  -x, --exec
          Run the command directly, not through the shell. Much like the `-x` option of the watch command.
  -p, --use-pty
          Run the command through a pseudo-TTY so commands that colorize on terminals can keep color output.
  -O, --diff-output-only
          Display only the lines with differences during `line` diff and `word` diff.
      --ignore-spaceblock
          Ignore diffs where only consecutive whitespace blocks differ.
  -A, --aftercommand <after_command>
          Executes the specified command if the output changes. Information about changes is stored in json format in environment variable ${HWATCH_DATA}.
      --after-command-result-write-file
          Passes `${HWATCH_DATA}` to `aftercommand` as a temporary file path instead of inline json data.
  -l, --logfile [<logfile>]
          logging file. if a log file is already used, its contents will be read and executed.
      --force-logfile-overwrite
          continue even if an existing logfile is empty or unreadable
  -s, --shell <shell_command>
          shell to use at runtime. can also insert the command to the location specified by {COMMAND}. [default: "sh -c"]
  -n, --interval <interval>
          seconds to wait between updates [default: 2]
      --precise
          Attempt to run as close to the interval as possible, regardless of how long the command takes to run
  -L, --limit <limit>
          Set the number of history records to keep. only work in watch mode. Set `0` for unlimited recording. [default: 5000]
      --tab-size <tab_size>
          Specifying tab display size [default: 4]
      --diff-plugin <diff_plugin>
          Load a diffmode plugin dynamic library.
  -d, --differences [<differences>]
          highlight changes between updates
  -o, --output [<output>]
          Select command output. [default: output] [possible values: output, stdout, stderr]
  -K, --keymap <keymap>
          Add keymap
  -h, --help
          Print help
  -V, --version
          Print version

Keybind

Watch mode keybind(Default).

Key	Action
↑, ↓	move selected screen(history/watch).
pageup, pagedn	move selected screen(history/watch).
home, end	move selected screen(history/watch).
Tab	toggle select screen(history/watch).
←	select watch screen.
→	select history screen.
Alt+←, Alt+→	Watch window scrll left/right.
Shift+Alt+←, Shift+Alt+→	Watch window scrll start/end.
Q	exit hwatch.
Esc	unfiltering.
Shift+D	delete selected history.
Shift+X	clear all history except selected history.
Ctrl+c	cancel.
H	show help window.
B	toggle enable/disable border.
C	toggle color.
N	switch line number display.
R	toggle reverse mode.
M	toggle mouse support.
T	toggle the UI (history pane and header).
Backspace	toggle the history pane.
D	switch diff mode.
0	disable diff.
1	switch watch type diff.
2	switch line type diff.
3	switch word type diff.
Shift+O	show only lines with differences(line/word diff mode only).
O	switch output mode(output->stdout->stderr).
W	Toggle wrap.
F1	only stdout print.
F2	only stderr print.
F3	print output.
Ctrl+N	Forcus next keyword.
Ctrl+P	Forcus before keyword.
Shift+S	show summary infomation in history.
+	increase interval.
-	decrease interval.
P	Pause/unpause execution.
/	filter history by string.
*	filter history by regex.

Custom keybind

Can customize key bindings by using the -K Option. Write it in the format keybind=funciton.

hwatch -K ctrl-p=history_pane_up -K ctrl-n=history_pane_down command...

Keybind functions that can be specified are as follows.

function	description
up	Move up
watch_pane_up	Move up in watch pane
history_pane_up	Move up in history pane
down	Move down
watch_pane_down	Move down in watch pane
history_pane_down	Move down in history pane
scroll_right	Move page right in watch pane
scroll_horizontal_end	Move page right end in watch pane
scroll_left	Move page left in watch pane