WATCH(1)

👑 WATCH(1) — the girlies' guide to watch

okay bestie so this is watch, straight out of the General Commands Manual, and honestly? she's iconic. let's get into it 💅

---

✨ NAME ✨

watch — run a program on repeat and show its output fullscreen 🌈

---

🌸 SYNOPSIS 🌸

watch [option ...] command

---

💖 DESCRIPTION 💖

so watch literally runs your command over and over, showing you its output and errors (the first screenful of it). the whole point is you get to sit there and watch the program's output change over time like it's a livestream. by default command gets run every 2 seconds and watch just keeps going until you interrupt it. there's a header up top telling you when command started, how long it's been running, and its exit code. chef's kiss 🎀

---

✨ OPTIONS ✨

• -b, --beep — beep if command exits with a non-zero status. it's giving alarm clock ⏰
• -c, --color — interpret ANSI color and style sequences. let her be colorful 🦋
• -C, --no-color — do not interpret ANSI color and style sequences. muted mode, no cap
• -d, --differences[=permanent] — highlight what changed between successive updates. if you pass the optional permanent argument, watch shows you all the changes since the very first iteration. the permanent argument needs to be linked to the option, like -d1 or --differences=1. can't just float around on its own bestie
• -e, --errexit — freeze the updates when command errors out, and exit after you press a key. the exit code of watch will be the code command exits with. and if signal n is what killed command, the exit code will be 128 + n. dramatic exit, love that for her 💀
• -f, --follow — instead of clearing the screen on every update, watch scrolls the output, kinda like how tail -f works. ⚠️ this option is not compatible with any option that tracks the output of the screen, such as the --differences, --chgexit and --eqexit options. pick a lane girl
• -g, --chgexit — exit when the visible output of command changes. heads up: changes that are off the screen because your screen is small or the output is huge will not cause watch to exit
• -n, --interval seconds — set the update interval. values smaller than 0.1 and larger than 2678400 (that's 31 days, wild) get converted into those respective bounds. both . and , work for any locale. and the WATCH_INTERVAL environment variable can 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. she's punctual 💅
• -q, --equexit cycles — exit when the 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 that's normally shown at the top of the screen
• -w, --no-wrap — turn off line wrapping. long lines get 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, but shell features (environment setup, variable and pathname expansion, etc.) will be unavailable. trade-off city 😭
• -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. impatient queen behavior, valid
• q — quit watch. heads up: it currently does not interrupt a running command (unlike terminating signals, such as the SIGKILL following Ctrl+C) 🛑
• s — take a screenshot. it'll be saved in the working directory, unless specified otherwise by --shotsdir. if command is running at the moment, the screenshot gets taken as soon as it finishes ⭐

---

🌈 EXIT STATUS 🌈

• 0 — Success. does not represent the 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 watch is affected by the following environment variables:

• WATCH_INTERVAL — update interval, follows the same rules as the --interval command line option
• COLUMNS — terminal screen character width. set it to override autodetection
• LINES — terminal screen character height. set it to override autodetection

---

💜 NOTES 💜

POSIX option processing is used (i.e., option processing stops at the first non-option argument). this means flags after command don't get interpreted by watch itself. iykyk

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

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.

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.

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

watch uname -r

---

💀 BUGS 💀

when the terminal dimensions change, its contents changes are not registered on the next command run. --chgexit will not trigger that turn, and the counter of --equexit will not restart even if command output changes meanwhile. --differences highlighting is reset. yeah... she's got a little quirk, we still love her 🌸

---

📬 REPORTING BUGS 📬

please send bug reports to procps@freelists.org. tell them the group chat sent you 💌

---

and that's the whole vibe bestie — this was procps-ng, dated 2025-04-16, and watch(1) ate and left no crumbs. go watch something, you got this 👑💖