Syncdir V3.1
============
Author: Kyle A. York
Address
  internet:   noesis@cats.ucsc.edu
  compuserve: 72125, 1533
  (please use the i-net account when possible, i don't check the cis
   account often)

Restrictions
============
This is freeware, NOT public domain. I retain the license, so please:

  * Don't sell copies of this product without contacting me.
  * Always leave my name, and if you use any code in your programs
    I would appreciate a note somewhere in the documentation that
    it was based upon my code.
  * If you modify the code, SAY SO! I don't want to be blamed for your
    mistakes :)

  + This is not a real requirement but I would appreciate if you mail me
    a note telling me you use this, or hate it :) This enables me to
    mail updates and make fixes.

Purpose
=======
  This program is used to synchronize directory trees. Its primary purpose 
  was to keep my home, notebook, and office machines in sync with minimum 
  effort and overhead.

History
=======
  V0.5 (never released) : first stab
  V1.0 working 16 bit dos version
  V1.5 included source (I forgot to include it with V2.0)
  V2.0 (limited release) : added long filename support
  V3.0 complete rewrite. versions for dos, win95, winnt and unix
  V3.1 changed ``dos/fileAttrGet(...)'' to prevent a novell issue
       updated the document (finally)
       added a hard-error handler for the 16 bit version to
         prevent the (A)bort, (R)etry (F)ail message (always
         returns to (F)ail).

<<IMPORTANT>>
=============
I've made every attempt to check this program for correctness, but
data-loss is always possible, especially using the '/d' and '/dd'
switches. Also, read the platform specific notes and the bug list!

Format
======
  syncdir source [dest] [flags]

source : source directory. must exist
dest   : destination directory. will be created if it doesn't exist.
flags:
  /a		add files found in {source} to {dest}
  /c		copy files found in {source} and {dest} regardless of timestamp
  /u		copy files found in {source} that are newer than those found 
		in {dest}
  /d[d]	delete files in {dest} not found in {source}
		for /dd : delete subdirectories also
  /f[acdu] 
		do not prompt before adding, copying, deleting, or updating
  /v		verbose mode
  /q		quite mode
  /n		no action
  /l[+][!][name]
		if [+] is present, append to log file, else overwrite
		if [!] is present, only log errors, else log all actions
		if [name] is present, use it as the log file name. 
		default is ``syncdir.log'' in the current directory
  /i		begin include file list (see notes). default is '*' 
  /x		begin exclude file list (see notes)
  /t		reset source file timestamp (see notes)
  /b		work in both directions (see notes)
  /g#   set granularity to # ms. Files times that differ <= # ms are 
        considered equal

Notes
=====
  1. matching
     the matching algorithm is simple, and allows a single wild-card
     character, '*', which matches any zero or more characters. thus,
     ``*.bak'' matches any files with the extension ``.bak'', and
     ``*\back\*'' matches all subdirectories named ``back''

     Common mistake: ``inc*'' will <<not>> match any files, because
                     all files begin with a path!
                     usually, ``*\inc*'' is meant!

  2. include/exclude file lists
     These are lists of file masks, seperated by ';' or whitespace. 
	   The following statements are equivalent:
		   /i*.bak;*.lib;*.obj;*\debug\*
		   /i *.bak *.lib *.obj *\debug\*

  3. source timestamp
	   some file systems keep track of the last time a file was accessed for
	   read or write. it is often convenient for this not to change
	   (especially during backups), so using '/t' will reset the timestamp
	   to its original value after a copy operation.

  4. both directions
	   this allows the selected operation to go in both operations, so if
	   a file in the destination directory is newer than one in the source,
	   the update is performed destination to source.

  5. mutually exclusive operations
	   '/c' and '/u' cannot be used together (for obvious reasons)
	   '/b' and '/c' cannot be used together
	   if '/b' is used, '/a' and '/d' cannot be used together

  6. dangerous stuff: '/d' and especially '/dd' can be dangerous operations,
	   especially when used with '/f' since these will delete file and/or
	   directories without prompting. use these at your own risk.
	   (actually, while debugging this program i inadvertantly deleted
	   the source and all of the backups by using these flags. oops!)

  7. The actions are performed in the following order: delete, copy, add,
     to minmimize the possiblity of running out of disk space.

Program Return Values
=====================
  0   no error
  1   invalid parameter
  2   cannot open log file
  3   source directory does not exist
  4   destination directory does not exist and can not be created
  5   out of memory
  6   cannot create temporary file
  7   temporary file overflow

Errors
======
  An error arises if a source and destination are not both files
or directories, in which case the log file will contain the the
offending entries with ``Error''

  An ambiguity occurs during ``update'' if the source and destination 
files have the same time stamp but are different sizes.


Platform Specific Notes
=======================
DOS
===
The DOS versions is a 16 bit program compiled with Borland's Turbo-C 2.0.

It uses two temporary files, located in one of the following directories:
  if ``tmp'' is defined in the environment, its value is used
  otherwise if ``temp'' is defined in the environment, its value is used
  otherwise the current directory is used.

It also requires around 200K in which to run (I've not actually tested
the absolute minimum. It requires 128K for buffers, and around 32K for
miscelaneous data. I added a few K for fluff.)

All directories use the backslash as a seperator, and all subdirectory
names have a backslash, '\',  before and after the name.
Command line options are denoted by a '/'.

Due to the buffering used, the maximum number of files in either the
source or destination directories (not combined) lies somewhere between 
45,000 and 300,000, depending upon the average length of the path to the
file (see ``sfiletbl.txt'' for implementation details).

The following options are unavailable:
  /g : granularity. ignored if present.
  /t : reset last-access time. this will cause a harmless warning,
       ``cannot set file stats'' if the source file is read-only.
       it will also needlessly slow down the file copying.
  /v : verbose. ignored if present.

When working, pressing ``Esc'' will bring up the:
  ``[C]ontinue, [S]top, [A]bort'' 
menu. [C]ontinue continues processing as if nothing happened, [S]top will
finish the current action and then stop, and [A]bort will halt the current
action and stop, possibily leaving a partially copied file.

When prompting for an action, the action will be displayed followed by
"(Y/y/N/n)?" on a new line.
   'Y' is ``yes to all'' and will assume yes to all similar questions 
       (for example, selecting ``yes to all'' for DELETE will not prompt 
        again for more deletes, but will prompt for ADDs or COPYs)
   'y' is ``yes to this one action only''
   'N' is ``no to all'' and will assume no to all similar questions
   'n' is ``no to this one action only''

Windows 95 and Windows NT
=========================
This is a 32 bit program compiled with Microsoft Visual C 5.0. Although
typically run from the command line, in verbose mode it uses a GUI for 
prompting and status.

All directories use the backslash as a seperator, and all subdirectory
names have a backslash, '\', before and after the name.
Command line options are denoted by a '/'.

The screen in verbose mode is a bit dense.

``Source'' column
  ``Add''    row : the number of files/bytes to be added to ``dest'' from ``source''
  ``Copy''   row : the number of files/bytes to be copied to ``dest'' from ``source''
  ``Delete'' row : the number of files/bytes to be deleted from ``source''
``Destination'' column
  ``Add''    row : the number of files/bytes to be added to ``source'' from ``dest''
  ``Copy''   row : the number of files/bytes to be copied to ``source'' from ``dest''
  ``Delete'' row : the number of files/bytes to be deleted from ``dest''
``Remaining'' column
  This is simply the sums of the prior two columns.

``Total'' bar represents the total amount of copying completed.
``File''  bar resresents the amount of copying completed for the current file.

``Elapsed''    the amount of time elapsed since the program began.
``Remaining''  a guess of the amount of time remaining, based on BPS
``B/s''        the number of bytes copied per second


When an ``execute'' prompt appears either under the GUI or the command line,
the possible responses are:

  ``yes''        execute this command and ask again
  ``yes to all'' execute this command and all LIKE commands
                 If you answer ``yes to all'' for a ``delete,'' you will
                 still be prompted for ``add'' and ``copy,''
  ``no''         do not execute this command
  ``no to all''  do not execute this command, or and LIKE commands.

Finally, the ``cancel'' options:
  ``continue''                    select if ``cancel'' was hit by accident
  ``complete current operation''  finish this operation, then cancel
  ``cancel immediatly''           do not complete this operation. cancel now!
                                  this will delete the unfinished file.


At the command line, ``cancel'' is selected by pressing the ``esc'' key.

Unix
====
Note: I've never implemented this. I know how, I simply haven't yet
      bothered. In the event it does get implemented, here is how
      it would work.

This is a 32 bit program compiled with the GNU compiler (the compiled
version runs under Windows 95 and Window NT, but it should be
independant enough to compile and run under unix).
It is command line only, all prompting is done using standard calls.
Errors go to standard error, and status to standard output.
All directories use the foreward as a seperator, and all subdirectory
names have a forward slash, '/', before and after the name.
Command line options are denoted by a '-'.


Know Bugs or Issues
===================
* In the DOS version, the '/t' switch will cause file-copying to
  slow somewhat do to needless overhead of resetting the source-file
  stats. If the source file is read-only, this will present a
  warning, ``cannot set file stats''
* In the DOS version, if the temporary file are created anywhere
  in the source tree, the two files will be copied to the destination
  giving the appearance of two ``phatom'' files. The solution is to
  simply set the ``tmp'' or ``temp'' environment variables outside
  of the source tree.
* There is no ``file name qualification.'' This means if a
  directory path, say ``c:\foo\bar'' and the current directory
  is ``c:\foo,'' then even though '.\bar' and 'c:\foo\bar' are
  the same directory, i don't notice them as such. This can
  result in infinite recursion. Be careful!

