hwatch

hwatch - alternative watch command.

Description

hwatch is a alternative watch command, it developed started in 2018.
That records the result of command execution, can display it history and diffs, hook and run commands.

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

Official Distro Packages

Debian

hwatch has been accepted into Debian unstable, although availability may depend on mirror sync status.

If you need it immediately, use the release .deb package from GitHub Releases.

Fedora

Official Fedora packaging is in progress and not yet available from Fedora repositories.

EPEL

EPEL packaging is planned after Fedora packaging is finalized.

Alpine Linux (edge/testing)

bash
apk add hwatch

Packaging Status

This repository includes packaging metadata for Debian-style .deb builds and RPM-based distributions, and GitHub Releases publishes prebuilt archives plus generated .deb and .rpm assets while official distro packaging is being worked on.

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. Alpine packages are available today, and Debian/Fedora distribution repository submissions are still in progress.

Other Package Managers

Community-maintained packages are available in several ecosystems, but they may lag behind the latest upstream release.

macOS

bash
# brew
brew install hwatch

# MacPorts
sudo port install hwatch

Arch Linux (AUR)

bash
# paru
paru -S hwatch

# yay
yay -S hwatch

Nix

bash
nix profile install nixpkgs#hwatch

conda-forge

bash
conda install conda-forge::hwatch
# or
mamba install conda-forge::hwatch

mise/asdf

bash
# mise
mise use -g aqua:blacknon/hwatch

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

GitHub Releases

If you want the latest upstream release immediately, use the assets published on GitHub Releases.

Current release assets include:

Linux: x86_64-unknown-linux-gnu.tar.gz
Linux: x86_64-unknown-linux-musl.tar.gz
Linux: aarch64-unknown-linux-musl.tar.gz
Linux: x86_64-unknown-linux-musl.deb
Linux: x86_64-fedora.rpm
macOS: x86_64-apple-darwin.tar.gz
macOS: aarch64-apple-darwin.tar.gz
Windows: x86_64-pc-windows-msvc.zip

For generic .tar.gz assets:

bash
curl -LO https://github.com/blacknon/hwatch/releases/latest/download/hwatch-<VERSION>.<TARGET>.tar.gz
tar xf hwatch-<VERSION>.<TARGET>.tar.gz
sudo install -m 0755 bin/hwatch /usr/local/bin/hwatch

For the generated release packages:

bash
# Debian/Ubuntu-style systems
sudo dpkg -i hwatch-<VERSION>.x86_64-unknown-linux-musl.deb

# Fedora/RHEL-style systems
sudo dnf install ./hwatch-<VERSION>.x86_64-fedora.rpm

Cargo Install

bash
cargo install hwatch

Notes

Security

--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.

Usage

Command

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

Custom keybind

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

bash
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
scroll_horizontal_home	Move page left start in watch pane
page_up	Move page up
watch_pane_page_up	Move page up in watch pane
history_pane_page_up	Move page up in history pane
page_down	Move page down
watch_pane_page_down	Move page down in watch pane
history_pane_page_down	Move page down in history pane
move_top	Move top
watch_pane_move_top	Move top in watch pane
history_pane_move_top	Move top in history pane
move_end	Move end
watch_pane_move_end	Move end in watch pane
history_pane_move_end	Move end in history pane
toggle_focus	Toggle focus window
focus_watch_pane	Focus watch pane
focus_history_pane	Focus history pane
quit	Quit hwatch
reset	filter reset
delete	Delete selected history
clear_except_selected	Clear all history except selected history
cancel	Cancel
force_cancel	Cancel without displaying the exit dialog
help	Show and hide help window
toggle_color	Toggle enable/disable ANSI Color
toggle_line_number	Toggle enable/disable Line Number
toggle_reverse	Toggle enable/disable text reverse
toggle_mouse_support	Toggle enable/disable mouse support
toggle_view_pane_ui	Toggle view header/history pane
toggle_view_header_pane	Toggle view header pane
toggle_view_history_pane	Toggle view history pane
toggle_border	Toggle enable/disable border
toggle_scroll_bar	Toggle enable/disable scroll bar
toggle_diff_mode	Toggle diff mode
set_diff_mode_plane	Set diff mode plane
set_diff_mode_watch	Set diff mode watch
set_diff_mode_line	Set diff mode line
set_diff_mode_word	Set diff mode word
set_diff_only	Set diff line only (line/word diff only)
toggle_output_mode	Toggle output mode
set_output_mode_output	Set output mode output
set_output_mode_stdout	Set output mode stdout
set_output_mode_stderr	Set output mode stderr
toggle_wrap_mode	Toggle watch pane text wrap enable/disable
toggle_history_summary	Toggle history summary
interval_plus	Interval +0.5sec
interval_minus	Interval -0.5sec
toggle_pause	Toggle pause execution
prev_keyword	Focus previous keyword
next_keyword	Focus next keyword
change_filter_mode	Change filter mode
change_regex_filter_mode	Change regex filter mode

Configuration

Set configuration in enviroment

If you always want to use some command-line options, you can set them in the
HWATCH environment variable. For example, if you use bash, you can add
the following to your .bashrc:

bash
export HWATCH="--no-title --color --no-help-banner --border --with-scrollbar"

Set color configuration in enviroment

You can also customize the watch diff highlight colors with environment variables.

HWATCH_WATCH_FG: foreground color for watch diff highlights
HWATCH_WATCH_BG: background color for watch diff highlights

Accepted values are ANSI color names such as red, blue, lightcyan, color indexes 0-255,
hex colors like #RRGGBB, or RGB values like 255,0,0.

Example

Interval 3 second

Use the -n option to specify the command execution interval.

bash
hwatch -n 3 command...

Exit when output changes

Use -g to exit after the first detected change, like watch -g.

bash
hwatch -g command...

Use -g N to exit after N detected changes.

bash
hwatch -g 3 command...

Logging output

The command execution result can be output as a log in json format.

bash
hwatch -n 3 -l hwatch_log.json command...

When you check the json log, you can easily check it by using this script.

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:

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

Use shell function

If you want the shell function to be executed periodically, you can specify the shell command to be executed with -s as follows.

bash
# bash
hwatch -n 3 -s 'bash -c "source ~/.bashrc; {COMMAND}"' command...

# zsh
hwatch -n 3 -s 'zsh -c "source ~/.zshrc; {COMMAND}"' command...

ANSI Color code

If you want to see output colored with ANSI color code, enable color mode.

To enable color mode, run hwatch with the -c option.
Alternatively, you can enable / disable the color mode with the <kbd>C</kbd> key during execution.

bash
hwatch -n 3 -c command...

Diff view

To enable color mode, run hwatch with the -d option.

There are several "diff modes" available.
Switching can be done with the <kbd>D</kbd> key.

bash
hwatch -n 3 -d command...

Watch diff

Line diff

Word diff

History filtering

You can filter history as a string with <kbd>/</kbd> key and as a regular expression with <kbd>*</kbd> key.

Run batch mode

You can have command diffs output directly to stdout instead with -b option of getting them as a TUI app.

bash
hwatch -b command...

Plugins

You can load diffmode plugins as dynamic libraries with --diff-plugin.
This allows you to add custom diff rendering for command output.

numeric-diff example

The bundled numeric-diff plugin highlights numeric changes when the surrounding text stays the same.
Built-in plugins use the core default gutter for line numbers and can optionally override gutter text or style when they need a custom prefix.

Build the plugin:

bash
cargo build --manifest-path plugins/numeric-diff/Cargo.toml --release

Then load it with --diff-plugin:

bash
hwatch --diff-plugin plugins/numeric-diff/target/release/libhwatch_plugin_numeric_diff.dylib -d line "seq 3 | awk '{ print \"value=\" $1 * int(rand() * 10) }'"