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
```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
```
### Alpine Linux (edge/testing)
```bash
apk add hwatch
```
### mise/asdf
```bash
# mise
mise use -g aqua:blacknon/hwatch
# asdf
asdf plugin add hwatch
asdf install hwatch latest
asdf global hwatch latest
```
### Cargo Install
```bash
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:
```bash
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
```shell
$ 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 []
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
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
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 []
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 to use at runtime. can also insert the command to the location specified by {COMMAND}. [default: "sh -c"]
-n, --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
Set the number of history records to keep. only work in watch mode. Set `0` for unlimited recording. [default: 5000]
--tab-size
Specifying tab display size [default: 4]
--diff-plugin
Load a diffmode plugin dynamic library.
-d, --differences []
highlight changes between updates
-o, --output [