/usr/local/stat_watch/texts/ Current File: //usr/local/stat_watch/texts/help_job_file.txt
REGARDING THE JOB FILE

Default Usage:
    - All files or directories need to be referred to by full path (Beginning with "/") unless specified otherwise
    - Any line beginning with a file or directory will result in that file or directory (and all files within) being passed over
    - You can include any amount of whitespace at the start or end of a line, it will not be interpreted
    - Spaces and special characters don't need to be quoted or escaped
    - All other lines that don't match this or the control strings described below will be ignored.

Control Strings:
    - Lines beginning with the following control strings have special meanings and can be declared multiple times:
        - If a line begins with the full path to a file or directory (starting with "/") that file or directory will be passed over (as if declared with the "--ignore" flag)
        - "Ignore" Same as above - pass over the file or directory that is specified
        - "*" or "Ignore*" - Pass over all files and directories whose full path begins with the string that follows
        - "R" or "IgnoreR" - Pass over all files and directories that match the following Perl interpreted regex
        - "I" - Add the following file or directory to the list of files and directories to be checked (as if it was listed at the command line). Has no effect with "--diff"
        - "Include" - Interpret the contents of the following file as if it was listed at the command line as a job file
            - Every line of the included job file will be read and interpreted before interpreting any of the rest of the lines in the current file
        - "BackupR" - If a file matches the regular expression that follows, and the appropriate flags are set, they will be backed up
        - "Backup+" - In any instance where there are changes to the following file, it will be backed up
        - "Time-" - Stat changes to this file will not be reported by "--diff" if the only change is to mtime or ctime
            - Useful if a file is regularly getting touched by a process, but still want to track changes to it otherwise
        - "MD5R" - If a file matches the regular expression that follows, also capture the file's MD5 sum for comparison
        - "MD5" -
            - If a file's name and full path matches the exact string that follows, also capture the file's MD5 sum for comparison
            - If "MD5" is alone on a line, then capture MD5 sums for everything (as if the "--md5" flag was used)
            - This will require that the perl modules 'Digest::MD5' and 'Digest::MD5::File' are installed
    - Lines beginning with the following control strings have special meanings, but only the last declaration will be interpreted:
        - "BackupD" - This specifies the directory to backup files to. The directory must already exist and be writable, or Stat Watch will error out
        - "BackupMD" - A number specified here will set the minumum number of days a backed up file should be kept
        - "BackupMC" - A number here will set the maximum number of copies of a file that should be backed up (after the minumum retention has been met)
        - "Log" - Placing a full path to a file after this will tell Stat Watch where to log
        - "Max-depth" - A number here will set the maximum depth of directories that the script can recurse into (default 20)
            - Any directories deeper than this will be logged on each run, assuming that the "Log" control string is used
    - Lines beginning with the following control strings have special functionality for running a Stat Watch job (using the "--run" flag). Only the last declaration of these will be interpreted
        - "Name" - This is used to designate the name of the job. Without this set, Stat Watch will not run this job
        - "Email" - This is used to designate an email adress (or multiple space separated email addresses) for results to be sent to 
        - "Expire" - When this is followed by a unix timestamp, the job will stop running after that timestamp is reached, and all associated files (except for the log file) will be deleted fifteen days later
        - "Max-run" - If a job is started only to find an earlier iteration of itself running, and that earlier iteration has been running for more than this number of seconds, that job will be killed
        - "Prune-max" - Pruning old backups will occur X out of every Y runs. "Prune-max" designates the "Y". Without this set, the default is 10.
        - "Prune-chance" - Pruning old backups will occur X out of every Y runs. "Prune-chance" designates the "X". Without this set, the default is 1.
        - "Email-no-changes" - If this control string is present, send emails even if there are no changes.
        - "Log-max" - A number following this control string will designate the maximum size (in bytes) of the log before it's trimmed. Without this set, the default is 10485760.
        - "Email-retain" - the number of days to retain old email messages. If this is set to "0", old email messages will never be deleted.
        - "Working-dir" - The working directory for Stat Watch to keep all files related to this job in.
            - If this is not specified, Stat Watch will assume that the directory containing the job file should be used as a working directory for this job.
        - "Nice" - The niceness at which to run any potentially processor intensive commands. By default this is 15.
        - "Db-watch" - If desired, this should be followed by the full path to a db_watch job file
            - Run 'stat_watch --help db-watch' for more information
        - There are five control strings that allow the user to run a custom script at various points during the process of a typical Stat Watch job run: "Run-start", "Run-post", "Run-end", "Run-pre-e", and "Run-post-e":
            - For any of these, the full path to the script must be used.
            - Anything following the control string (and any whitespace after it) will be interpreted by the "eval" command
            - "Run-start" - The script specified here will run immediately previous to the first "--record" "--backup" or "--diff" command
            - "Run-post" - The script specified here will run immediately after all of the "--record" "--backup" or "--diff" commands have completed
            - "Run-pre-e" - The script here will run immediately previous to sending an email message (Only if there's reason to send one)
            - "Run-post-e" - The script here will run immediately after sending an email message (Only if there's reason to send one)
            - "Run-end" - The script specified here will run immediately before the job exits
    - Control strings can have any amount of whitespace before or after them on the line. It will not be interpreted.
    - When a file is included via "Include", the entirety of that file will be interpreted before the going on to interpret the next line
    - For "*" or "R", any line matching a directory will result in that directory and all files and subdirectories it contains being passed over

Other Rules:
    - Any line that doesn't match what's described above will be ignored
    - Lines cannot begin with more than one control string
    - If a directory is included with "I" or given at the command line that would otherwise be ignored due to entries in the file, those entries will be ignored while it is being checked