URIS
  http://raa.ruby-lang.org/project/dirwatch/
  http://www.codeforpeople.com/lib/ruby/dirwatch/

NAME
  dirwatch v0.0.3

SYNOPSIS
  dirwatch [options]+ [directory = .] [mode = watch] 

DESCRIPTTION
  dirwatch maintains a database that mirrors the state of a directory.  when
  run dirwatch uses this database as reference to determine when files have
  been created, modified, updated, deleted, or were pre-existing and then to
  trigger configurable commands for those conditions.

  mode must be one of

    create or c -> initialize database
    watch  or w -> maintain database and take actions
    list   or l -> dump database to stdout in yaml

  the configuration can be specified on the command line or searched for in 
  [".dirwatch/", "."].  if a configuration is not specified or
  located the builtin config is used - this should only be for testing.

  dirwatch uses the config's enumeration of the actions to be taken when
  files are discovered to have been created, modified, updated, deleted or
  existing to determine which commands to run.  the action section of the config
  contains subsections for each of actions created, modified, updated, deleted,
  and existing of the form

    commands:
      -
        command: echo @file
        pattern: .*.txt
      -
        command: cat @file

    filters:
      -
        command : while read file;do echo $file;done 
        pattern: .*.exe

  for commands the token '@file' or '$file' will be replaced with the currently
  processed file and the command run iff it matches pattern.  pattern is not
  required, in which case the command will always be run for that action.  in
  order to assist programs in knowing whether they are running due a created,
  modified, deleted, or existing action the environment variable
  'DIRWATCH_ACTION' will be set in the child process to contain the type of
  action.  additionally the environment var 'DIRWATCH_PATH' will be set to
  contain the full path to the entry in question.  commands are spawned
  asynchronously (all at once) and then all processes are waited.  

  filters are run in a similar fashion to commands, only instead of spawning a
  process for each file in question the filter is spawned once with all files in
  question on standard input.  the reason for the two methods is for cases using
  a command (vs. a filter) would result in 10000 very expensive processes being
  spawned at once and bringing a system to it's knees.  the filter can process
  the list of files and, for instance, batch up commands and one big command,
  run them sequentially, etc.
  
  this probably sounds more complicated than it is and this is compounded by the
  fact that i can't seem to write : better to just try running 

     ~ > dirwatch -t

  to view a sample config file, which should be rather self explanatory.

ENVIRONMENT
  export SQLDEBUG=1 -> cause sql debugging info to be logged

FILES
  directory/.dirwatch/              -> dirwatch data files 
  directory/.dirwatch/db            -> sqlite database file
  directory/.dirwatch/db.schema     -> sqlite database schema 
  directory/.dirwatch/lock          -> sentinal lock file used for nfs safe access 
  directory/.dirwatch/dirwatch.conf -> default configuration location
  directory/.dirwatch/dirwatch.log  -> default log file when running under cron 
  directory/.dirwatch/*             -> misc files used by locking subsystem 

CONFIG
  default path -> dirwatch.conf
  search path  -> [".dirwatch/", "."]

DIAGNOSTICS
  success -> $? == 0
  failure -> $? != 0

AUTHOR
  ara.t.howard@noaa.gov

BUGS
  > 1 && < 42

OPTIONS
  --pattern=pattern, -p 
        watch only files matching pattern (__not__ shell glob) 
  --files_only, -f 
        ignore everything but files - (default directories and files) 
  --flat, -F 
        do not recurse into subdirectories - (default recurse) 
  --help, -h 
        this message 
  --verbosity=verbostiy, -v 
        0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info) 
  --log=path, -l 
        set log file - (default stderr) 
  --log_age=log_age 
        daily | weekly | monthly - what age will cause log rolling (default 
        nil) 
  --log_size=log_size 
        size in bytes - what size will cause log rolling (default 1mb) 
  --config=path, -c 
        valid path - specify config file (default 
        directory/.dirwatch/dirwatch.conf) 
  --template=[path] 
        valid path - generate a template config file in path (default stdout) 

EXAMPLES

  0) initialize a directory for watching 

    ~ > dirwatch dir create

  1) create a config (to edit afterwards) 

    ~ > dirwatch -t > conf && vi conf

  2) watch a dir taking actions described in config 

    ~ > dirwatch dir watch -c conf 

  3) watch a dir taking actions described in config, but not recursing into any
     subdirectories

    ~ > dirwatch dir watch -c conf --flat

  4) watch a dir taking actions described in config, ignoring all but regular
     files (ignoring directories, device files, etc.) 

    ~ > dirwatch dir watch -c conf --files_only

  5) watch a dir taking actions described in config, ignoring all entries
     (directory or file) except those that match pattern 

    ~ > dirwatch dir watch -c conf --pattern='.(OIS|OIF)$'

    note that the config allows a pattern to be specified for each command to be
    run; the command line switch, however, is applied before any command
    specific pattern filters - it is a pre-filter.

  6) run using all defaults in the current directory 

    ~ > dirwatch

  7) dump contents of database in yaml format

    ~ > dirwatch dir list

  8) crontab entry the watch a directory using config found in
     "directory/.dirwatch/dirwatch.conf".  note that dirwatch uses a logfile
     of 'directory/.dirwatch/dirwatch.log' when run without a controling tty.

     */15 * * * * /full/path/to/dirwatch /full/path/to/directory