Watch mode
From Zacess Scenes v1.1.0. Edit this page on GitHub
The build monitor for projects in any language: what it shows, the command each kind of project runs, bacon for Rust, the status bar, choosing the scenes, the keys and desktop notifications. The tones are described in sound sets and every setting in configuration. To show how each command typed in a shell ended instead, see follow mode.
zacess-scenes watch shows how the project in the current folder stands. It runs the project's
check once at the start and again whenever a file changes. A Rust project uses
bacon when it is installed; every other project runs its own command
and its exit code decides pass or fail:
- Passing: a calm scene,
wavesunless you choose others, with a large ALL GOOD banner, a check mark and a short caption that belongs to the scene. Any warnings are listed below it. - Failing: a fail scene,
stormunless you choose others, with a large banner, a cross, a caption and the first errors or failing tests, each with its location where one is given. The banner reads BUILD FAILED with bacon and FAILED for any other command. Warnings follow the errors. - Recovered: when a failing build is fixed, the pass scene opens out from the middle of the
screen over the fail scene in two seconds, its edge traced by a ring of small sparkles. The status
bar reads
recoveredand a recovered caption shows for a few seconds. Under reduced motion the opening takes three and a half seconds and has no sparkles. Nothing flashes. - Warnings are marked
!and drawn in the theme's warning colour. Errors and failing tests are marked with a cross and drawn in the theme's error colour, so the two differ in shape as well as colour. Only bacon reports warnings, so the count shows only for Rust projects watched with it.
Use watch mode
cd my-project
zacess-scenes watch # the project's own check, in any language
zacess-scenes watch --cmd "javac Main.java" # any command; its exit code decides
zacess-scenes watch test --volume 30 # bacon's test job, with quieter tones
zacess-scenes watch --no-sound # no tones at all
zacess-scenes watch --scene koi-pond,tea --fail-scene flood --sounds marimba --notifyThe command for each project
The nearest folder at or above the current one with one of these files decides the command. It runs
through the system shell (sh on macOS and Linux, cmd on Windows) in that folder.
| The folder has | Runs |
|---|---|
Cargo.toml |
bacon when it is installed (see below), otherwise cargo check |
package.json |
The check script, then test (unless it is the placeholder npm init writes), then build, then lint, with pnpm, yarn or bun when their lockfile is there and npm otherwise |
go.mod |
go build ./... && go vet ./... |
pyproject.toml, setup.py, setup.cfg or requirements.txt |
python3 -m pytest -q when there are tests (tests/, test/ or test_*.py), otherwise python3 -m compileall -q ., which still catches a syntax error. python on Windows |
pom.xml |
mvn -q compile |
build.gradle or build.gradle.kts |
The Gradle wrapper's build when the project has one, otherwise gradle -q build |
A .sln, .csproj or .fsproj file |
dotnet build |
Package.swift |
swift build |
mix.exs |
mix compile |
composer.json with a test script |
composer test |
Gemfile and Rakefile |
bundle exec rake |
Makefile |
make |
CMakeLists.txt and a build folder |
cmake --build build |
--cmd runs any other command instead, from the nearest project folder or the current one. A
command's tools have to be installed: pytest for Python tests, for example. When they are not, the
failure screen shows the tool's own message, such as No module named pytest.
Files are looked at for a change every 0.7 seconds and a run starts once they have been still for
0.3 seconds, so a save that writes several files starts one run. Folders that hold build output,
dependencies or tool state, such as .git, target, node_modules, dist, build,
__pycache__ and .venv, are not watched, since a change there is usually the command's own
doing. A run under way is stopped when another starts and when the watch mode quits, along with
anything it started.
The lines shown for a failure are the ones that read as errors, such as error:, FAILED,
AssertionError or panicked at, with a place such as src/app.py:12 split out where a line
starts with one. When no line looks like an error, the last line of output is shown, so a failure
always says something.
Rust and bacon
bacon is a separate program, not part of Zacess Scenes (see NOTICE.md). Install it once:
cargo install --locked baconWithout bacon a Rust project runs cargo check like any other command. Naming one of bacon's jobs
asks for bacon, so without it zacess-scenes watch clippy prints the install command and stops.
| Job | Runs |
|---|---|
check (the default) |
cargo check |
check-all |
cargo check --all-targets |
clippy |
cargo clippy |
test |
cargo test |
With bacon the number keys switch the job. bacon reruns the job whenever a file in the project
changes. Its JSON report export is turned on
through bacon's --config-toml option and written to a temporary folder that is removed on quit.
The project's own bacon.toml is read as usual and never written to.
The bottom row is a status bar in the theme's colours:
my-project │ check │ ✓ passing · 2 warnings │ 12s agoWhile the build fails it reads ✗ failing in the theme's error colour with the count of errors or
failed tests. Outside bacon the job is the command itself. While a run is under way it adds
· running. Notes such as paused,
sound off and no sound player follow at the end. On a narrow terminal the notes go first, then
the age and then the job.
--theme, --fps, --motion, --reduced-motion and --colour work as they do for the scenes.
Under reduced motion the storm has no lightning. A change of scene, sound set or volume is written
in the status bar for three seconds, such as scene koi-pond · sounds marimba. The status bar
shows quiet hours while quiet hours keep the sound off.
Choosing the scenes
| Flag | Variable | Config | Does |
|---|---|---|---|
--scene <names> |
ZACESS_SCENE |
pass |
The scenes to show while the build passes, separated by commas. Pass and general scenes and your own Lua scenes |
--fail-scene <names> |
ZACESS_FAIL_SCENE |
fail |
The scenes to show while it fails. Fail scenes and your own Lua scenes |
rotation |
fixed keeps the first scene, cycle moves to the next scene in the list each time the state comes round again and shuffle picks another at random, never the same twice running |
||
interval |
With cycle or shuffle, also change the scene every this many minutes while the state stays the same. 0, the default, changes only on a new result |
Without a list, the pass list is waves followed by every other pass and general scene and the
fail list is storm followed by every other fail scene. n and b always move through the list
showing; a list of one scene widens to every scene of its kind, so the keys always have somewhere
to go.
Keys in watch mode
| Key | Does |
|---|---|
1 to 4 |
With bacon, switches to the check, check-all, clippy or test job |
r |
Runs the job or the command again |
n |
Shows the next scene for the current state |
b or N |
Shows the scene before |
m |
Moves to the next sound set and plays its pass tone |
+ and - |
Raise and lower the volume by 10. = and _ work too, so Shift is not needed |
s |
Turns sound on or off |
a |
Turns the background sound on or off |
[ and ] |
Lower and raise the background sound's volume by 10 |
p or Space |
Pauses and resumes the animation. The status keeps updating |
h or ? |
Shows the keys again |
q, Esc or Ctrl+C |
Quits, stops bacon or the command and gives the terminal back |
A scene changes at most once every 0.4 seconds however fast n or b is pressed, so the picture
is never replaced faster than three times a second.
Notifications
--notify sends a desktop notification when a build starts failing and when it is fixed, such as
my-project: check failed with 2 problems. Screen readers announce notifications, so the state can
be heard without looking at the terminal. They use the system's own tools:
| System | Sent with |
|---|---|
| macOS | osascript and display notification |
| Linux | notify-send |
| Windows | A PowerShell toast or a tray balloon where the toast is not available. No module is needed |
Notifications are off by default. Turn them on with --notify, ZACESS_NOTIFY=1 or enabled = true under [notifications] in the config. --no-notify turns them off again for one run.