Back to project page

NAME

watchdir - watch for changes in a directory tree

SYNOPSIS

watchdir [OPTION] DIRECTORY OUTPUTDIR
watchdir [-h|-V]

DESCRIPTION

watchdir monitors the given DIRECTORY and all its subdirectories for changes. At regular intervals, the names of the files and directories which have changed are written to a uniquely named file in the OUTPUTDIR directory:

Changes to directories are treated in the same way:

All paths are given relative to the top-level DIRECTORY. Directory names always end in /, which means that just / on its own in a change file means that the top-level directory itself changed (i.e. a file or directory was removed from it).

The change files in OUTPUTDIR are given names of the form YYYYMMDD-hhmmss.pid where YYYY is the 4-digit year, MM is the 2-digit month, DD is the 2-digit day of the month, hh, mm, ss are 2-digit hours, minutes, and seconds in the 24-hour clock, and pid is the process ID of watchdir.

Note that OUTPUTDIR must not be a subdirectory of DIRECTORY.

OPTIONS

-i, --dump-interval SEC

Write change files every SEC seconds. The default is 30 seconds. No change files are written when there are no changes to report.

-f, --full-scan-interval SEC

Rescan DIRECTORY every SEC seconds, to pick up any changes that might have been missed. The default is 7200 seconds (2 hours).

-e, --exclude PATTERN

A glob(7) pattern to exclude. Any file or directory, in any subdirectory of DIRECTORY, which matches this pattern will be ignored.

This option can be specified multiple times.

The default is to exclude *.tmp and *~.

-r, --recursion-depth NUM

Descend no more than NUM directories deep into DIRECTORY. The default is 20. It is not advisable to set this too high as it may cause excessive consumption of system resources.

-q, --queue-run-interval SEC

Process the inotify(7) change queue every SEC seconds. The default is 2 seconds. This will rarely need to be changed.

-m, --queue-run-max SEC

Spend no longer than SEC seconds processing the change queue before checking inotify(7) again, to avoid overflows caused by many changes happening at once. The default is 5 seconds. This will rarely need to be changed.

-h, --help

Print a usage message on standard output and exit successfully.

-V, --version

Print version information on standard output and exit successfully.

NOTES

If you watch a lot of directories, you will probably need to increase the kernel parameter fs.inotify.max_user_watches, for example:

sysctl -w fs.inotify.max_user_watches=1048576

You may also need to increase fs.inotify.max_user_instances.

The change files can be used directly as input to rsync(1)'s --files-from option, like this:

rsync --delete -dlptgoDH --files-from=OUTPUTDIR/20140731-112501.1234 DIRECTORY remote:/dir/copy/

A similar command line is used by continual-sync(8) when doing a partial sync.

Changes to file permissions are not listed - only changes which alter the contents of a file or its last-modification time.

BUGS

When watching a directory with a large number of subdirectories, it may take watchdir(1) an inconveniently long time to finish scanning through them all and begin watching for changes.

REPORTING BUGS

This is part of the continual-sync package. Report bugs in continual-sync to <https://codeberg.org/a-j-wood/continual-sync/issues> or use the contact form linked from the package home page: <http://www.ivarch.com/programs/continual-sync.shtml>

SEE ALSO

continual-sync(8), rsync(1), glob(7), lsyncd(1), rsync-inotify(1), inosync(1)

COPYRIGHT

Copyright 2014, 2021, 2023 Andrew Wood.

License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Back to project page