/usr/local/stat_watch/texts/ Current File: //usr/local/stat_watch/texts/help_flags.txt
USAGE AND COMMAND LINE FLAGS

stat_watch --assume [JOB_FILE] [DIRECTORY]
    - From this point forward, when ever Stat Watch is run within a directory or one of its subdirectories, assume that a specific job file should be included (as if with the "-i" or "--include" flag)
    - If Stat Watch is run within the directory specified with the "-i" or "--include" flags or with the "--no-assume" flag, these assumptions will be ignored
    - Only one job file can be specified as being assumed for each directory - running "--assume" again and specifying the same directory will overwrite the job file to use
    - The PWD will be checked first, followed by its parent directory and so on - thus if both '/var' and '/var/log' have been given assumptions, and a Stat Watch command is run within the directory '/var/log/tmp', the assumptions for '/var/log' will be used and the assumptions for '/var' will not be used
    - If this flag given only the job file and no directory, an assumption is created for the PWD
    - If this flag given only a directory, the script will report assumptions for the directory given (if any)
    - If this flag given no arguments, It will return whether or not these is an assumption for the PWD
    - If instead of a job file, the flag "--remove" is given, remove any flags for the directory given
        - Or the PWD, if no directory is given
    - If "--assume" is only given the "--list" flag, this will list all existing assumptions

stat_watch --backup [REPORT FILE]
    - Create backups of files specified using a Stat Watch report file and the settings within a job file
    - The file must be a Stat Watch report file
    - The "-i" or "--include" flag can be used to specify a job file and that file must have "BackupD" and "BackupR" or "Backup+" control strings present
    - The "--backupd" flag can be used, followed by the directory that you want to back up to
        - This is functionally the same as the "BackupD" control string in a job file
    - The "--backup+" flag can be used, followed by the full path of a file that you wish to back up. This flag can be used more than once.
        - This is functionally the same as the "Backup+" control string in a job file
    - The "--backupr" flag can be used, followed by perl regular expression to match in order to decide what files to backup. This flag can be used more than once.
        - This is functionally the same as the "BackupR" control string in a job file
    - If you modify the "BackupR" or "Backup+" settings and re-run "--backup", it will compare stats of existing backups and only save files that are different / not present
        - Note that backed-up versions of files that are no longer matched will not be removed

stat_watch --backup-file [FULL PATH TO FILE]
stat_watch -a [FULL PATH TO FILE]
    - Create a backup of the specified file
    - If multiple files are specified, they will all be backed-up
    - The "-i" or "--include" flag can be used to specify a job file and that file must have the "BackupD" control string present
    - The "--backupd" flag can be used, followed by the directory that you want to back up to
        - This is functionally the same as the "BackupD" control string in a job file
    - The "--comment" flag can be used followed by a comment to provide details about the backup that's being performed
        - If multiple files are specified for backup, the comment will be applied to all of those files
    - The "--hold" flag can be used to prevent Stat Watch from removing this file as part of file pruning

stat_watch --backup-stat [BACKED-UP FILE]
stat_watch --bs [BACKED-UP FILE]
    - Output the stats of a backed-up file
    - The backed-up file can be referenced either by its full path, or by its display name as output by "--list"
    - More than one file can be given as arguments

stat_watch --comment [BACKED-UP FILE] [COMMENT]
    - Add a comment to an existing backed-up file
    - The backed-up file can be referenced either by its full path, or by its display name as output by "--list"
    - The "--hold" flag can also be used to add a hold on this file

stat_watch --compare [FILE 1] (optional [FILE 2])
    - Compares stats of two files and outputs a diff of their content
    - The files presented can be actual filenames, or backup display names as output by "--list"
    - If only given one file name, and that file is the full path to a backup or the display name of a backup, this will output the differences between that backup and the file as it currently exists
    - If only given one file name, and there are existing backups of that file, compares to the most recent backup of that file

stat_watch --create
    - Asks the user key questions in order to create a Stat Watch job file with the information necessary to watch and backup key user files
    - By default, this will enable backup for files that end with the following: .php, .php4, .php5, .php7, .pl, .pm, .py, .js, .json, .css, .cgi .htm, .html, .htaccess, .htpasswd, .sh, .rb
    - What files are being checked and what files are being backed-up can be modified by editing the .job file that is created

stat_watch --diff [REPORT FILE 1] [REPORT FILE 2]
    - Compare two Stat Watch report files, weed out files that match ignore rules, output information on what has changed
    - The "--ignore" flag can be used to specify a specific file or directory that you want to ignore
        - This is functionally the same as listing a file without a control string in a job file
    - The "-i" or "--include" flag can be used to specify a job file
    - The "-o" or "--output" flag will specify a file to poutput to, otherwise /dev/stdout will be used
    - The "-f" or "--format" flag allows you to choose a number of options for how the details should be output:
        - "text" separates out what has changed and how, and outputs in plain text format
        - "html" separates out what has changed and how, and outputs in html format
            - "html" is deprecated and will be removed in future versions
        - "diff" outputs the lines that were different with "<" and ">" characters to indicate which file they came from. 
    - The "--backup" flag will result in files being backed-up. "BackupD" and "BackupR" or "Backup+" lines must be set in the job file for this to be successful
    - The "--no-check-retention" flag mean that when creating backups, existing files will not be checked for retention
        - This is optimal if you're regularly running Stat Watch with the "--prune" flag (as is done automatically with the "--run" flag)
    - The "--no-ctime" flag tells the script to ignore differences in ctime. This is useful if you're comparing against a restored backup.
    - The "--no-partial-seconds" limits the comparison of timestamps to full seconds
        - This functionality will become the default in future versions
    - The "--before" and "--after" flags can be used to specify which is the earlier Stat Watch report file and which is the later
        - Without these flags, the mtimes of the files are used to determine which is which
    - The "--backup-md" and "--backup-mc" flags can be used to set the vaules typically set by the "BackupMD" and "BackupMC" control strings
    - Note: If "--diff" is only given one file as an argument and that file is an existing backup, this will instead funcation as the "--compare" flag

stat_watch --email-test [EMAIL ADDRESS]
    - Sends a test message to the email address specified so that the end recipient can see an example

stat_watch --hold [BACKED-UP FILE]
    - This flags a backed-up file such that it will not be pruned
    - The backed-up file can be referenced either by its full path, or by its display name as output by "--list"
    - You can add "--comment" followed by a comment in order to add a comment on this file as well

stat_watch --list [FILE]
    - This will list the available backups that Stat Watch has taken of a specific file
        - The output shows the file's display name, the time the backup was taken, the file's size in bytes, and any comments that might have been made for the backup
    - It is not necessary to specify an include file or backup directory
        - Stat Watch will check all directories that it has ever backed-up to in hopes of giving the most comprehensive answer possible.

stat_watch --md5-test
    - Test to see if everything necessary is in place for checking the md5sum of files

stat_watch --prune
    - Go through the backup directory and remove files older files
    - The "-i" or "--include" flag must be used to specify a job file and that file must have "BackupD" string present
        - Alternately, the "--backupd" flag can be used to specify a backup directory
    - Any files outside of the range specified by the "BackupMD" and "BackupMC" control strings will be removed
        - The "--backup-md" and "--backup-mc" flags can be used to set the vaules typically set by the "BackupMD" and "BackupMC" control strings

stat_watch --rd [REPORT FILE] (optional [FILE NAME])
stat_watch --report-details [REPORT FILE] (optional [FILE NAME])
    - Output the timestamps for when Stat Watch started gathering stats for each of the directories
    - If a file name is provided, also output the stats that were take of that file, if it exists
        - The user can specify multiple files to output stats of
    - The flags "--file" or "-f" can be used to specify files, and "--report" or "-r" can be used to specify the report
        - In this manner, if you have multiple reports and are not sure which will contain the stats of the file, you can run `stat_watch --rd -f [FILE NAME] -r [REPORT FILE]`, making it easy to backspace over the name of the report file so that you can try again
    - Instead of giving a file name, we can use "--all" to output stats of all of the files within the report

stat_watch --record [DIRECTORY] ([DIRECTORY 2] ...)
    - Creates a Stat Watch report of all of the files within the directories specified (and the subdirectories thereof) including their current stat data
        - You probably want to use the "-o" flag or redirect output to a file
    - The "-v" or "--verbose" flag can be used to have the directories output to STDERR
    - The "-i" or "--include" flag can be used to specify a job file
    - The "-o" or "--output" flag will specify a file to output to, otherwise /dev/stdout will be used
    - The "--max-depth" flag can be used to specify the maximum directory depth to search to
    - This is the default functionality. Technically the "--record" flag is not necessary
    - The "--md5" flag will result in the MD5 sums of all files being captured in addition to their stats
        - This will require that the ./modules/md5.pm file be present, as well as the perl modules 'Digest::MD5' and 'Digest::MD5::File'
        - This will cause the process to take longer and generally isn't necessary - the combination of mtime, ctime, and file size is usually enough to detect if a change has occurred
    - The "--ignore-on-record" flag will result in individual files being checked against ignore rules
        - Otherwise only directories are checked against this rules, and weeding out things to be ignored only occurrs during "--diff"
        - Use of this flag results in larger file sizes for Stat Watch reports, but generally reduces processing time overall
    - The "--as-dir" flag can be followed by a string of text that will be used to replace the directory name when recording the full file path
        - For example, running "./stat_watch.pl --record /home/account --as-dir "/home/different/path" will result in the file "/home/account/file.txt" to be listed as "/home/different/path/file.txt"
        - This is useful for situations where you want to capture information for backed-up files and compare them to files in place.
    - The "--ext-stat" flag can be used to use the stat binary rather than perl's internal stat
        - This functionality is deprecated (as it is significantly less performant) and will be removed in future versions

stat_watch --restore [BACKED-UP FILE]
    - Given a backed-up file, restore it to its original location
    - The backed-up file can be referenced either by its full path, or by its display name as output by "--list"

stat_watch --run [JOB FILE]
    - Runs the necessary commands to complete a Stat Watch job, including checking the stats of files, determining th edifferences, and backing up files when necessary
    - [JOB FILE] is the .job file created when running Stat Watch with the "--create" flag
    - Adding the "--errors" flag after the file will prevent any errors from being routed to /dev/null

stat_watch --unhold [BACKED-UP FILE]
    - Removes the hold from a backed-up file, meaning that it is once again elidgable to be pruned per the rules specified by the "BackupMD" and "BackupMC" control strings
    - The backed-up file can be referenced either by its full path, or by its display name as output by "--list"

stat_watch --help
stat_watch -h
    - Outputs basic help information

stat_watch --help use-cases
stat_watch --help flags
stat_watch --help job
stat_watch --help backups
stat_watch --help job-files
stat_watch --help files
stat_watch --help tests
stat_watch --help assume
stat_watch --help conf
stat_watch --help db-watch
    - Outputs information regarding the specific aspect of Stat Watch requested

stat_watch --version
    - Outputs version and changelog information


OTHER FLAGS

--config [CONFIGURATION FILE]
    - Allows the user to specify an alternate configuration file
    - The "--config" flag and alternate configuration file MUST come before any other flags or arguments

--locate
    - Tells Stat Watch to determine its own location programatically rather than trust the hard coded location
    - This flag must come immediately after the primary flag
    - This was only added for testing purposes; it is unlikely that there will be a use case for it outside of that