GNU-WATCH(1) General Commands Manual GNU-WATCH(1) NAME gnu-watch - execute a program periodically, showing output fullscreen SYNOPSIS gnu-watch [option ...] command DESCRIPTION gnu-watch runs command repeatedly, displaying its output and errors (the first screenful). This allows you to watch the program output change over time. By default, command is run every 2 seconds and gnu-watch will run un- til interrupted. A header informs of the start and running time of command as well as its exit code. OPTIONS -b, --beep Beep if command has a non-zero exit. -c, --color Interpret ANSI color and style sequences. -C, --no-color Do not interpret ANSI color and style sequences. -d, --differences[=permanent] Highlight the differences between successive updates. If the op- tional permanent argument is specified then gnu-watch will show all changes since the first iteration. The permanent argument needs to be linked to the option, such as -d1 or --differences=1. -e, --errexit Freeze updates on command error, and exit after a key press. The exit code of gnu-watch will be the code command exits with. If sig- nal n is the cause of command termination, the exit code will be 128 + n. -f, --follow Instead of clearing the screen at each update, gnu-watch will scroll the output similiar to how tail -f works. This option is not compat- ible with any option tracking the output of the screen, such as the --differences, --chgexit and --eqexit options. -g, --chgexit Exit when the visible output of command changes. Changes that are off the screen due to small screen size or large output will not cause gnu-watch to exit. -n, --interval seconds Specify update interval. Values smaller than 0.1 and larger than 2678400 (31 days) are converted into these respective bounds. Both '.' and ',' work for any locale. The GNU-WATCH_INTERVAL environment variable can be used to persistently set a non-default interval (following the same rules and formatting). -p, --precise Execute command --interval seconds after its previous run started, instead of --interval seconds after its previous run finished. If it's taking longer than --interval seconds for command to complete, it is waited for in either case. -q, --equexit <cycles> Exit when output of command does not change for the given number of cycles. -r, --no-rerun Do not run the program on terminal resize, the output of the program will re-appear at the next regular run time. -s, --shotsdir Directory to save screenshots into. -t, --no-title Turn off the header normally shown at the top of the screen. -w, --no-wrap Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line. -x, --exec Pass command to an exec(3) call instead of sh -c. The program will start a bit quicker. Shell features (environment setup, variable and pathname expansion, etc.) will be unavailable. -h, --help Display help text and exit. -v, --version Display version information and exit. KEY CONTROL spacebar Issue command immediately. If it's running at the moment, it is not interrupted and its next round will start without delay. q Quit gnu-watch. It currently does not interrupt a running command (as opposed to terminating signals, such as the SIGKILL following Ctrl+C). s Take a screenshot. It will be saved in the working directory, unless specified otherwise by --shotsdir. If command is running at the mo- ment, the screenshot will be taken as soon as it finishes. EXIT STATUS 0 Success. Does not represent command exit code. 1 Errors unrelated to command operation. 2 Errors related to command execution and management (not its exit code). any non-zero (--errexit) With --errexit the last exit code of command is returned. ENVIRONMENT The behavior of gnu-watch is affected by the following environment vari- ables. GNU-WATCH_INTERVAL Update interval, follows the same rules as the --interval command line option. COLUMNS Terminal screen character width. Set to override autodetection. LINES Terminal screen character height. Set to override autodetection. NOTES POSIX option processing is used (i.e., option processing stops at the first non-option argument). This means that flags after command don't get inter- preted by gnu-watch itself. Non-printing characters are stripped from program output. Use cat -v as part of the command pipeline if you want to see them. EXAMPLES To watch the contents of a directory change, you could use gnu-watch -d ls -l If you have CPUs with a dynamic frequency and want to observe it change, try the following. The command is passed to the shell, which allows you to make the pipeline. The quotes are a feature of the shell too. gnu-watch -n1 'grep "^cpu MHz" /proc/cpuinfo | sort -nrk4' To monitor the up status of your servers, saving a copy of the output of each run to a file, you may use this. The -p makes the command execute every 10 seconds regardless of how long it took to complete the previous run. gnu-watch -n10 -p -d '{ date; for i in 10.0.0.31 10.0.0.32 10.0.0.33; do R=OK; ping -c2 -W2 "$i" &>/dev/null || R=FAIL; echo "$i: $R"; done } | tee -a ~/log' You can watch for your administrator to install the latest kernel with gnu-watch uname -r BUGS When the terminal dimensions change, its contents changes are not regis- tered on the next command run. --chgexit will not trigger that turn and the counter of --equexit will not restart even if command output changes mean- while. --differences highlighting is reset. REPORTING BUGS Please send bug reports to procps@freelists.org. procps-ng 2025-04-16 GNU-WATCH(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | KEY CONTROL | EXIT STATUS | ENVIRONMENT | NOTES | EXAMPLES | BUGS | REPORTING BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gnu-watch&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>