# watch

## NAME



           watch - execute a program periodically, showing output fullscreen
    


## SYNOPSIS



           **watch**[_option_ ...] _command_
    


## DESCRIPTION



           **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
           **watch** will run until 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 optional _permanent_ argument is specified then **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 **watch** will be the code _command_
                  exits with. If signal **n** is the cause of _command_
                  termination, the exit code will be 128 + **n**.
    
           **-f** , **--follow**
                  Instead of clearing the screen at each update, **watch** will
                  scroll the output similiar to how _tail -f_ works. This
                  option is not compatible 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 **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
                  **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 **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 moment, 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 **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 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 interpreted by **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
    
                  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.
    


* * *