 *****************************************************************************
 *                                ZipSnap 2.1                                *
 *                                 2007-08-26                                *
 *                        Copyright 2007 Zach Scrivena                       *
 *                           zachscrivena@gmail.com                          *
 *                       http://zipsnap.sourceforge.net/                     *
 *                                                                           *
 *                                RELEASE NOTES                              *
 *****************************************************************************

ZipSnap is a simple command-line incremental backup tool for directories.

ZipSnap creates archives that are collections of point-in-time snapshots.
An archive is just a directory of catalogs (plain text files compressed as
ZIP files) and compressed volumes (ZIP files). When a snapshot is added to
an archive, a new compressed volume is created, containing only new or
modified files and directories. A catalog is used to store information on
the snapshots and contents of the archive. Files are automatically numbered
with a timestamp. Runs on any OS with the Java Runtime Environment (JRE 6+).
ZipSnap is free software written in Java and released under the GNU GPL
license (version 3).


MAIN FEATURES
-------------
 * ZipSnap creates archives that are collections of point-in-time snapshots.
    An archive is just a directory of catalogs (plain text files compressed as
    ZIP files) and compressed volumes (ZIP files).

 * Catalogs are written cumulatively, i.e. a later catalog contains all the
    information from previous catalogs. Therefore, only the latest catalog is
    needed when adding/restoring snapshots.

 * Catalogs and compressed volumes are automatically timestamped as
    ArchiveName.yyyyMMdd-HHmmss.n, with extensions .txt.zip and .zip
    respectively, where n is the snapshot number.

 * Because ZipSnap never modifies a catalog or compressed volume after it is
    created, archives can be stored on write-once-only media.

 * ZipSnap supports GLOB and REGEX filters for file/directory names, or their
    full (relative) pathnames.

 * When ADDING a snapshot, ZipSnap looks for the latest catalog in the archive
    and performs file matching between the current directory contents and
    previously archived files and directories as described by the catalog.
    By default, files and directories are matched by full (relative) pathname,
    size, and last-modified time (in milliseconds). The new or modified files
    and directories in the current directory (i.e. the unmatched contents) are
    then added to a new compressed volume (by default, a ZIP file), and a new
    catalog (by default, a plain text file compressed as a ZIP file) is
    written. If the archive does not exist yet, a new archive is created.

 * When RESTORING a snapshot, ZipSnap looks for the latest catalog in the
    archive and by default, restores the latest snapshot from the archive.
    File matching is performed between the current directory contents and the
    snapshot contents, to determine the unmatched files and directories that
    need to be extracted from their respective compressed volumes, and to be
    deleted from the current directory. By default, files and directories are
    matched by full (relative) pathname, size, and last-modified time (in
    milliseconds).


SYSTEM REQUIREMENTS
-------------------
 A Java Runtime Environment (JRE 6+) is required. The latest version of the
 JRE can be downloaded from <http://java.sun.com/j2se>.


LICENSE
-------
 ZipSnap is released with source code under the GNU General Public License
 (version 3). The license document can be found in license.txt.


INSTALLATION & EXECUTION
------------------------
 The ZipSnap utility is downloaded as a single Zip file with the following
 contents:

   ZipSnap.jar           ZipSnap executable JAR archive
   readme.txt            Release notes (this file)
   license.txt           License document (GNU GPLv3)
   unix/ZipSnap          Unix/Linux script for executing ZipSnap
   windows/ZipSnap.bat   Windows batch file for executing ZipSnap
   src/                  Source files

 No installation is necessary --- just unzip the downloaded file and you are
 ready to go. Assuming that the executable JAR archive ZipSnap.jar is in the
 current directory, simply execute the following at the command-line:

   java -jar ZipSnap.jar

 Several pages of documentation (usage syntax, notes, and examples) should fill
 the screen. The use of the Windows batch file (windows/ZipSnap.bat) or the
 Unix/Linux script (unix/ZipSnap) is recommended because it enables you to
 simply execute ZipSnap instead of java -jar ZipSnap.jar. Further instructions
 are given in the respective files.


DOCUMENTATION: USAGE SYNTAX, NOTES, AND EXAMPLES
------------------------------------------------
USAGE:  java -jar ZipSnap.jar  [command]  <switches>  ["Archive"]

[Commands]:

 a  ADD a snapshot of the current directory to the archive:
     ZipSnap looks for the latest catalog in directory ["Archive"] and performs
     file matching between the current directory contents and previously
     archived files and directories as described by the catalog. By default,
     files and directories are matched by full (relative) pathname, size, and
     last-modified time (in milliseconds). The new or modified files and
     directories in the current directory (i.e. the unmatched contents) are
     then added to a new compressed volume (by default, a ZIP file), and a new
     catalog (by default, a plain text file compressed as a ZIP file) is
     written. If the archive does not exist yet, a new archive is created.

 r  RESTORE a snapshot from the archive to the current directory:
     ZipSnap looks for the latest catalog in directory ["Archive"] and by
     default, restores the latest snapshot from the archive. File matching is
     performed between the current directory contents and the snapshot
     contents, to determine the unmatched files and directories that need to be
     extracted from their respective compressed volumes, and to be deleted from
     the current directory. By default, files and directories are matched by
     full (relative) pathname, size, and last-modified time (in milliseconds).

 i  Display INFORMATION on the archive:
     ZipSnap looks for the latest catalog in directory ["Archive"] and displays
     the file counts for each snapshot in the archive.

<Switches>:

 -s, --simulate        Simulate only; do not actually add/restore snapshot
 -i, --ignorewarnings  Ignore warnings; do not pause

 -c, --crc             Use file CRC-32 checksum for file matching, in addition
                        to full (relative) pathname, size, and last-modified
                        time (in milliseconds)
 -t, --time:[x]        Use a x-millisecond time-tolerance for file matching
                        (by default, a 0-millisecond time-tolerance is used)
     --all             Add/extract ALL files/directories when adding/restoring
                        a snapshot without performing file matching first
     --forceadd        Force addition of snapshot, even if it is identical to
                        the last snapshot (by default, an identical snapshot
                        is not added)

 -l, --list            Create a list of files/directories to be added/extracted
                        when adding/restoring a snapshot
 -z, --zip:<x>         Add files/directories to a ZIP volume using compression
                        level x, with 0 and 9 representing minimum and maximum
                        compression respectively (by default, maximum
                        compression is used)
 -j, --jar:<x>         Add files/directories to a JAR volume ...

     --snapshot:[x]    Restore snapshot number x (by default, the latest
                        snapshot is restored)
 -o, --overwrite:[y|n] Always[y]/never[n] overwrite existing files/directories
                        when restoring a snapshot
 -d, --delete:[y|n]    Always[y]/never[n] delete unmatched existing
                        files/directories when restoring a snapshot
 -p, --path:["x"]      Include additional search path x for volume files when
                        restoring a snapshot (can be used repeatedly to specify
                        multiple search paths)

 -f, --filter:["x"]       Apply GLOB filter string x for file/directory names
 -F, --FILTER:["x"]       ... for full (relative) file/directory pathnames
 -e, --filterregex:["x"]  Apply REGEX filter string x for file/directory names
 -E, --FILTERREGEX:["x"]  ... for full (relative) file/directory pathnames

["Archive"]:

 ZipSnap archive, i.e. the directory containing the catalogs and compressed
 volumes

NOTES:

 1. ZipSnap creates archives that are collections of point-in-time snapshots.
     An archive is just a directory of catalogs (plain text files compressed as
     ZIP files) and compressed volumes (ZIP files).

 2. Catalogs are written cumulatively, i.e. a later catalog contains all the
     information from previous catalogs. Therefore, only the latest catalog is
     needed when adding/restoring snapshots.

 3. Catalogs and compressed volumes are automatically timestamped as
     ArchiveName.yyyyMMdd-HHmmss.n, with extensions .txt.zip and .zip
     respectively, where n is the snapshot number.

 4. The latest catalog selected by ZipSnap is the catalog with the largest
     snapshot number in the archive directory. To break ties, the catalog with
     the latest last-modified time is selected.

 5. When restoring a snapshot, ZipSnap looks for volume files with specific
     timestamps and snapshot numbers, in the archive directory. Additional
     search paths, if specified, are also searched. To break ties, the volume
     with the latest last-modified time is selected.

 6. Because ZipSnap never modifies a catalog or compressed volume after it is
     created, archives can be stored on write-once-only media.

 7. ZipSnap supports GLOB and REGEX filters for file/directory names, or their
     full (relative) pathnames. The supported REGEX patterns are given by the
     Java API documentation.

    GLOB Patterns and Wildcards:
      *    Matches a string of zero or more characters
      ?    Matches exactly one character
     [ ]   Matches exactly one character from within the brackets:
             [abc]      matches a, b, or c
             [!abc]     matches any character except a, b, or c (negation)
             [a-z0-9]   matches any character a through z, or 0 through 9,
                         inclusive (range)
     { }   Matches exactly one comma-delimited string from within the braces:
             {a,bc,def} matches either a, bc, or def

EXAMPLES:

 1. ADD a snapshot to the archive; if the archive does not exist, a new archive
     is created:
    java -jar ZipSnap.jar a "C:\Backups\Work"

 2. RESTORE the latest snapshot from the archive:
    java -jar ZipSnap.jar r "C:\Backups\Work"

 3. RESTORE the latest snapshot from the archive, and always overwrite existing
     files/directories, but never delete unmatched existing files/directories:
    java -jar ZipSnap.jar r --overwrite:y --delete:n "C:\Backups\Work"

 4. RESTORE snapshot number 2 from the archive:
    java -jar ZipSnap.jar r --snapshot:2 "C:\Backups\Work"

 5. RESTORE only jpg or html files in the latest snapshot from the archive:
    java -jar ZipSnap.jar r --filter:"*.{jpg,html}" "C:\Backups\Work"

 6. Display INFORMATION on the archive:
    java -jar ZipSnap.jar i "C:\Backups\Work"


FEEDBACK?
---------
 Comments, suggestions, and bug reports are welcomed! Please send any feedback
 you have about ZipSnap to <zachscrivena@gmail.com>.

 The latest version of ZipSnap can be obtained from
 <http://zipsnap.sourceforge.net/>.
