# watch — Run a Command Repeatedly and Watch Its Output

> Practical guide to watch — repeat commands at fixed intervals and follow changing output live, with custom intervals, diff highlighting and exit conditions.

Source: https://www.jpkc.com/db/en/cheatsheets/shell-system/watch/

<!-- PROSE:intro -->
watch runs a command over and over at a fixed interval and shows you only its latest output – perfect for keeping an eye on changing data such as disk usage, process lists, network connections or the status of a deployment. By default it repeats every two seconds; a handful of flags let you change the interval, highlight what changed or stop the loop automatically. This guide walks you through the options and patterns you actually reach for day to day.
<!-- PROSE:intro:end -->

## Basic Usage

`watch <command>` — Run a command every 2 seconds (default interval).

```bash
watch date
```

`watch -n <seconds> <command>` — Run at a custom interval.

```bash
watch -n 5 df -h
```

`watch -n 0.5 <command>` — Run every half second (sub-second intervals).

```bash
watch -n 0.5 'cat /proc/loadavg'
```

`watch '<command1> | <command2>'` — Watch a piped command (use quotes).

```bash
watch 'ps aux | grep nginx | wc -l'
```

## Display Options

`watch -d <command>` — Highlight differences between updates.

```bash
watch -d free -m
```

`watch -d=permanent <command>` — Highlight all changes since the first run (cumulative).

```bash
watch -d=permanent 'ls -la /tmp'
```

`watch -t <command>` — Hide the header (no title, interval, or command shown).

```bash
watch -t date
```

`watch --color <command>` — Preserve ANSI color codes in output.

```bash
watch --color 'ls --color=always -la'
```

## Exit Conditions

`watch -g <command>` — Exit when the output changes.

```bash
watch -g 'ls /tmp/upload/'
```

`watch -e <command>` — Exit on error (freeze output and wait for keypress).

```bash
watch -e 'curl -sf http://localhost:8080/health'
```

`watch -b <command>` — Beep when the command returns a non-zero exit code.

```bash
watch -b 'ping -c 1 -W 1 server.example.com'
```

## Common Patterns

`watch -n 1 'kubectl get pods'` — Monitor Kubernetes pod status.

```bash
watch -n 1 'kubectl get pods -n production'
```

`watch -d 'df -h'` — Monitor disk usage with change highlighting.

```bash
watch -d 'df -h'
```

`watch -n 2 'docker ps'` — Monitor running Docker containers.

```bash
watch -n 2 'docker ps --format "table {{.Names}}	{{.Status}}"'
```

`watch -n 5 'ss -tlnp'` — Monitor listening ports.

```bash
watch -n 5 'ss -tlnp'
```

`watch -n 1 'cat /proc/net/dev'` — Monitor network interface traffic in real-time.

```bash
watch -n 1 'cat /proc/net/dev'
```

`watch -g 'checksum.sh'` — Wait until a file changes (exit on change).

```bash
watch -g 'md5sum deploy.tar.gz'
```

`watch -n 10 'curl -so /dev/null -w "%{http_code}" <url>'` — Monitor HTTP status code of an endpoint.

```bash
watch -n 10 'curl -so /dev/null -w "%{http_code}" http://localhost:8080/health'
```

<!-- PROSE:outro -->
## Conclusion

watch turns any status command into a live dashboard without you having to write a `while` loop – for everyday use you rarely need more than `-n` for the interval, `-d` to highlight changes and `-g` to bail out automatically when something changes. Keep two things in mind. As soon as pipes, variables or glob patterns are involved, wrap the command in quotes (`watch '…'`) or run it via `watch bash -c '…'`, otherwise your current shell expands it once and watch just repeats the frozen result. And because watch runs the command again and again, only ever feed it read-only status and query commands – never anything that changes or deletes data.

## Further Reading

- [man7.org: watch(1)](https://man7.org/linux/man-pages/man1/watch.1.html) – official manual page covering every option with examples
- [procps-ng on GitLab](https://gitlab.com/procps-ng/procps) – upstream project that ships watch and other system tools
<!-- PROSE:outro:end -->

## Related Commands

- [top](https://www.jpkc.com/db/en/cheatsheets/shell-system/top/) – interactive real-time view of processes and system load
- [ps](https://www.jpkc.com/db/en/cheatsheets/shell-system/ps/) – snapshot of the currently running processes
- [journalctl](https://www.jpkc.com/db/en/cheatsheets/shell-system/journalctl/) – query and live-follow the systemd journal logs