inotify based node watcher
git clone git://git.2f30.org/wendy
Log | Files | Refs | README | LICENSE

commit 957c69dd673f38ee1a3504319d30383e8034294e
parent 24029110a1efd51f3cf4652c504c7c6eb12bb826
Author: Willy Goiffon <dev@z3bra.org>
Date:   Tue,  2 Jun 2020 09:50:02 +0200

Update README to be more concise

MREADME | 160+++++++++++++++++++------------------------------------------------------------
1 file changed, 38 insertions(+), 122 deletions(-)

diff --git a/README b/README @@ -1,122 +1,38 @@ - ╻ ╻┏━╸┏┓╻╺┳┓╻ ╻ - ┃╻┃┣╸ ┃┗┫ ┃┃┗┳┛ - ┗┻┛┗━╸╹ ╹╺┻┛ ╹ - -- by z3bra -=========================== - -(W)atch (EN)tire (D)irector(Y) is an inotify-based directory watcher. - -With wendy, you can watch event in directories or files, and launch a -specific command when an event occurs. - -The program is made the more simple possible, to leave the room to unlimited -uses. Be creative ! - -Every event raised by inotify is handled. Just sum them up to watch multiple -event at the same time. Here is the full table: -(see inotify(1) for a better explanation of those events) - - IN_ACCESS ........ 1 - IN_MODIFY ........ 2 - IN_ATTRIB ........ 4 - IN_CLOSE_WRITE ... 8 - IN_CLOSE_NOWRITE . 16 - IN_OPEN .......... 32 - IN_MOVED_FROM .... 64 - IN_MOVED_TO ...... 128 - IN_CREATE ........ 256 - IN_DELETE ........ 512 - IN_DELETE_SELF ... 1024 - IN_MOVE_SELF ..... 2048 - -To watch for both creation AND deletion in a directory, do some math: - - 256 + 512 = 768 - -then, pass that value to wendy so that she can watch after both of them (did I -just say 'she'?). - -You can also note that you can specify file/directory names either using the --f flag, or from stdin (in this case, the -f flag must be omited). -As a hidden feature, the watch mask is changed everytime the -m flag is -provided, and the inotify watches are set everytime the -f flag is given. So -you can wathc different mask on different file using the same command, and -that's pretty cool! - -Here are some examples: - - # Tell me whenever I have a new mail - wendy -m 256 -w ~/mails/INBOX/new espeak "You got a new mail" - - # On-the-fly recompilation - wendy -m 138 -w ~/src/dev/program/ make - - # Run a script against all files create in a directory - wendy -m 256 -w $HOME/autoupload sh -c '/usr/local/bin/upload.sh $WENDY_INODE' - - # watch different events for different files - wendy -m 256 -w ./directory -m 8 -w ./file.txt - -FAQ -=== - -> Can it work on a folder and sub folders ? - -Yes. By using two flags: `-r` and `-d`. The former will enable "recursive -mode", which will add a new watch on every node trigerring an IN_CREATE -event (note: you MUST add this even to the mask). -The latter (`-d`) will ignore every inode that is not a directory when -adding watches. This one is not mandatory, but could create duplicate -events reports by watching the same events on a directory, and each file -in this directory. - -Note: Because of the way inotify works, it is possible to encounter race -conditions when creating multiple levels on directories. Specifically, -when watching a directory "a", and doing `mkdir -p a/b/c`, the directory -"c" will most likely not be watched, because it was created before the -watcher on "b" was added. A workaround is to do it in multiple steps, -to give enough time to wendy to add the necessary watchers. - ---- - -> Can you explain why this exists? Doesn't inotifywait (from inotify-tools) do -> this exact same thing? - -When I first started wendy, I was not aware of inotifywait. It was just a good -programming exercise. - -With the time, I found wendy more and more useful, and added a few options to -make it faster and more 'generic' (It was first created to watch my mail -directory, to alert me of new mails). - -Today, I know that inotifywait can be used for everything wendy does Anyway, I -still prefer using wendy because of this: - - * inotifywait exits upon event reception [1] - * inotifywait does not allow to launch a command on event reception [2] - * inotifywait with multiple events can end in an infinite line [3] - * inotifywait only handle the file modification event (eg, wendy can use - the IN_ONLYDIR mask) - * 'wendy' is shorter/cooler to type! - -[1] I'm aware of the '--monitor' flag, but the only way to exec a command with -this is a pain that implies read, a while loop and so on. - -[2] In fact, you can, by doing "inotifywait -e <event> && command", and -wrapping it in a while loop. Well, don't forget to add a test to see if your -file still exists, to avoid infinite buggy loops. You'll end up with something -like: - - while test -e ~/path/to/my/file; do - inotifywait -e <event> ~/path/to/my/file && command - done - -Good luck with this, I prefer "wendy -m <mask> command" - -[3] one flag per event. events written in words: - - inotifywait -e access -e create -e delete -e modify -e attrib /path/to/file - -I prefer - - wendy -m 774 -w ~/path/to/my/file +wendy +===== +Inotify-based directory watcher. + +An arbitrary command is run whenever one or more filesystem events occur. +Events are reported through the inotify API, which is specific to the +Linux kernel. + +Features +----- +- Event(s) selection done with bitwise mask +- Automatically watch new directories in recursive mode +- Exports event informations in the command environment +- Path can be specified as argument or from `STDIN`. + +Usage +----- +Refer to wendy(1) manual page for details and examples. +The below commands are provided as a quick introduction. + +These commands will helps you recompile a project, preview the manual +page and upload it to a remote location (each running in a separate +terminal): + + ls *.[ch] | wendy make + wendy -w manual.1 sh -c 'clear;PAGER=cat man ./$WENDY_INODE' + wendy -rd -m 394 -w . rsync -av . remote:/dest + +Note: the numerical value "394" is a combination of event: MODIFY, +CLOSE_WRITE, MOVED_TO, CREATE. See `MASKS` in wendy(1) for all supported +events and their numeric values. + +Installation +----- +Edit config.mk if needed, then build/install with the following commands: + + make + make install