wendy

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

README (4617B)


      1   ╻ ╻┏━╸┏┓╻╺┳┓╻ ╻
      2   ┃╻┃┣╸ ┃┗┫ ┃┃┗┳┛
      3   ┗┻┛┗━╸╹ ╹╺┻┛ ╹
      4                 -- by z3bra
      5 ===========================
      6 
      7 (W)atch (EN)tire (D)irector(Y) is an inotify-based directory watcher.
      8 
      9 With wendy, you can watch event in directories or files, and launch a
     10 specific command when an event occurs.
     11 
     12 The program is made the more simple possible, to leave the room to unlimited
     13 uses. Be creative !
     14 
     15 Every event raised by inotify is handled. Just sum them up to watch multiple
     16 event at the same time. Here is the full table:
     17 (see inotify(1) for a better explanation of those events)
     18 
     19     IN_ACCESS ........ 1
     20     IN_MODIFY ........ 2
     21     IN_ATTRIB ........ 4
     22     IN_CLOSE_WRITE ... 8
     23     IN_CLOSE_NOWRITE . 16
     24     IN_OPEN .......... 32
     25     IN_MOVED_FROM .... 64
     26     IN_MOVED_TO ...... 128
     27     IN_CREATE ........ 256
     28     IN_DELETE ........ 512
     29     IN_DELETE_SELF ... 1024
     30     IN_MOVE_SELF ..... 2048
     31 
     32 To watch for both creation AND deletion in a directory, do some math:
     33 
     34     256 + 512 = 768
     35 
     36 then, pass that value to wendy so that she can watch after both of them (did I
     37 just say 'she'?).
     38 
     39 You can also note that you can specify file/directory names either using the
     40 -f flag, or from stdin (in this case, the -f flag must be omited).
     41 As a hidden feature, the watch mask is changed everytime the -m flag is
     42 provided, and the inotify watches are set everytime the -f flag is given. So
     43 you can wathc different mask on different file using the same command, and
     44 that's pretty cool!
     45 
     46 Here are some examples:
     47 
     48     # Tell me whenever I have a new mail
     49     wendy -m 256 -d ~/mails/INBOX/new -t 60 -e espeak "You got a new mail"
     50 
     51     # On-the-fly recompilation
     52     wendy -l | grep -i close_write
     53     IN_CLOSE_WRITE ... 8
     54     find -name "*.c" | wendy -m 8 -q -d ~/src/dev/program/ -t 1 -e make
     55 
     56 
     57     # Get up to date with community based projects
     58     wendy -m 770 -f /mnt/nfs/project/ -t 30 -e popup 'project updated'
     59 
     60     # watch creation in the directory, and modifications on a file
     61     wendy -m 256 -f ./my_dir -m 8 -f file.txt -e echo awesome!
     62 
     63 FAQ
     64 ===
     65 
     66 > Can it work on a folder and sub folders ?
     67 
     68 It does not. inotify does not handle this by default, and implementing this
     69 would make the code grow in complexity to a level I don't want to reach.
     70 But you could do something like:
     71 
     72     $ tree
     73     .
     74     ├── a
     75     ├── b
     76     │   ├── c
     77     │   └── d
     78     └── e
     79 
     80     5 directories, 0 files
     81 
     82     $ find a -type d | wendy -m 256 -v | cut -f2
     83 
     84 That will add a watch to each directory, and output the names of the file
     85 created (eg: "a/b/newfile").
     86 
     87 ---
     88 
     89 > Can you explain why this exists? Doesn't inotifywait (from inotify-tools) do
     90 > this exact same thing?
     91 
     92 When I first started wendy, I was not aware of inotifywait. It was just a good
     93 programming exercise.
     94 
     95 With the time, I found wendy more and more useful, and added a few options to
     96 make it faster and more 'generic' (It was first created to watch my mail
     97 directory, to alert me of new mails).
     98 
     99 Today, I know that inotifywait can be used for everything wendy does Anyway, I
    100 still prefer using wendy because of this:
    101 
    102     * inotifywait exits upon event reception [1]
    103     * inotifywait does not allow to launch a command on event reception [2]
    104     * inotifywait with multiple events can end in an infinite line [3]
    105     * inotifywait cna't read names from stdin
    106     * inotifywait only handle the file modification event (eg, wendy can use
    107       the IN_ONLYDIR mask)
    108     * inotifywait exits right when an event occur, wendy can treat all queued
    109       events at a specific period
    110     * inotify-tools : 164kb against 12kb for wendy (ok, not that relevant)
    111     * I like the name 'wendy' better
    112 
    113 [1] I'm aware of the '--monitor' flag, but the only way to exec a command with
    114 this is a pain that implies read, a while loop and so on.
    115 
    116 [2] In fact, you can, by doing "inotifywait -e <event> && command", and
    117 wrapping it in a while loop. Well, don't forget to add a test to see if your
    118 file still exists, to avoid infinite buggy loops. You'll end up with something
    119 like:
    120 
    121     while test -e ~/path/to/my/file; do
    122         inotifywait -e <event> ~/path/to/my/file && command
    123     done
    124 
    125 Good luck with this, I prefer "wendy -m <mask> -e command"
    126 
    127 [3] one flag per event. events written in words:
    128 
    129     inotifywait -e access -e create -e delete -e modify -e attrib /path/to/file
    130 
    131 I prefer
    132 
    133         wendy -m 774 -f ~/path/to/my/file
    134 
    135 ---
    136 
    137 > Would you prefer to fight one horse sized duck, or 10 duck sized horses ?
    138 
    139 Regarding size and number, I'd rather fight horses. Ducks are silly creatures.