[ANN] dirwatch-0.0.3

A

Ara.T.Howard

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
(e-mail address removed)

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




-a
--
===============================================================================
| EMAIL :: Ara [dot] T [dot] Howard [at] noaa [dot] gov
| PHONE :: 303.497.6469
| When you do something, you should burn yourself completely, like a good
| bonfire, leaving no trace of yourself. --Shunryu Suzuki
===============================================================================
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,482
Members
44,901
Latest member
Noble71S45

Latest Threads

Top