home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 6 File / 06-File.zip / gdiff.zip / gdiff.doc next >
Text File  |  1999-11-22  |  6KB  |  179 lines
  1. 21 November 1999.
  2.  
  3.              GDIFF: compute the difference between two files
  4.  
  5. Abstract:
  6.  
  7. GDIFF is an OS/2 program that will compute differences between 2 files, 
  8. and save the results to a "GDIFF formatted" difference file. 
  9. GDIFF can also "undifference" a "new" file, given an "original" file and 
  10. a GDIFF formatted difference file.
  11.  
  12. GDIFF will work on any type of file, it is NOT limited to text files.
  13.  
  14.                         -------------------
  15. Installation:
  16.    Just copy GDIFF.EXE to your path (say, to x:\OS2\APPS, where x:
  17.    is your boot drive). GDIFF.EXE does not require EMX!
  18.  
  19.                         -------------------
  20.  
  21. Syntax:
  22.  
  23. The basic syntax is:
  24.  
  25.  x:>GDIFF  oldfile newfile diff_file
  26.  
  27. diff_File will be created, and will contain the "GDIFF formatted"
  28. differences between oldfile and newfile.
  29.  
  30. Example:
  31.         x:>GDIFF  version1.doc version2.doc  version2.dif
  32.  
  33. To recreate newfile from oldfile and diff_file, and save the results
  34. to newfile_dup, use:
  35.  
  36.   x:>GDIFF oldfile diff_file newfile_dup
  37.  
  38. Example:
  39.         x:>GDIFF -u  version1.doc version2.dif  version2.new
  40.  
  41. The more complete syntax is:
  42.  
  43. Syntax:
  44.   x:>GDiff oldfile newfile [out_file] [-options]
  45.  
  46. If out_file is not specified, output is written to stdout
  47.  
  48. GDIFF recognizes the following options. Please note that options
  49. may appear anywhere (they do not have to be after the filenames),
  50. and that there should be no spaces between the - and the option:
  51.  
  52.        -MD4   -- just compute an MD4 of oldfile and newfile (or just
  53.                  the oldfile).
  54.                  example: x:>GDIFF -md4 bigprog.exe 
  55.  
  56.        -u     -- undifference. Newfile should be a Gdiff difference file.
  57.                  Note that GDIFF can be used with ANY "Gdiff formatted"
  58.                  difference file, not just difference files computed by
  59.                  this version of GDIFF.
  60.  
  61.        -b=nnn -- use a blocksize of nnn  (0<nnn<2000, 0=program chooses).
  62.                  Smaller blocksizes will lead to smaller difference files,
  63.                  but tend to increase execution time.
  64.                  By default, the program will choose a blocksize (based on the
  65.                  size of the input files).
  66.  
  67.        -q     -- quiet (suppress status  messages)
  68.                  Error messages will NOT be suppressed. Error messages always
  69.                  start with "ERROR" (not including the quotes).
  70.  
  71.        -v     -- verify
  72.                  Verify that the difference file will create a duplicate of
  73.                  the "newfile".  Note that a temporary file (on your TEMP 
  74.                  directory) will be created during this comparison, and 
  75.                  deleted afterwards.
  76.                  To use -v, you must specify an "out_file".
  77.                  When undifferencing, -v is ignored.
  78.  
  79.         -version  -- version
  80.                      Write version info to stdout (a one line message)
  81.  
  82.                         -------------------
  83.  
  84. Examples:
  85.  
  86.   x:>GDIFF  -v bigdoc.new bigdoc.old  bigdoc.dif
  87.   x:>GDIFF  -u bigdoc.new  bigdoc.dif > bigdoc.nu2
  88.   x:>GDIFFF  bigdoc.old bigdoc.new bigdoc.df2 -b=200
  89.   x:>GDIFF  -u -q bigdoc.new  bigdoc.df2 bigdoc.nu3
  90.   x:>GDIFF  -md4 bigdoc.new bigdoc.nu3
  91.  
  92. Notes:
  93.  
  94.     * GDiff uses the RSYNC algorithim to compute differences.
  95.       It is possible, though VERY unlikely, for the RSYNC algorithim
  96.       to produce an incorrect difference file. For circumstances where a
  97.       microscopic chance of failure is important, we recommend using
  98.       the -v option.
  99.  
  100.     * Specification of the GDIFF "difference file" format can be found at:
  101.          http://www.w3.org/TR/NOTE-gdiff-19970901.html
  102.  
  103.     * Information on the Rsync algorithim can be found at
  104.          http://www.samba.org/rsync/
  105.  
  106.     * GDIFF has been tested on a two versions of a 36M file (same contents,
  107.       but with contents rearranged). It took about a minute (on a Pentium 333).
  108.  
  109.     * GDIFF does not work well with compressed files (such as .ZIP files) --
  110.       these tend to change globally even if only a small set of the
  111.       archived files are different.
  112.  
  113.     * GDIFF.FOR contains the GDIFF source code (Fortran 77+, compiled with 
  114.       Watcom 11.0b).
  115.   
  116.     * REXX callable GDIFF procedures can be found in the rxRsync
  117.       package (http://www.srehttp.org/apps/rxrsync/).
  118.  
  119.                         ---------------------
  120. Error codes:
  121.  
  122. On successful completion, GDIFF will set a completion code, with
  123. values:
  124.  
  125.  0  - success
  126.  1  - failed to specify input file
  127.  2  - problem computing md4 (oldfile)
  128.  3  - problem computing md4 (newfile)
  129.  4  - bad -blocksize option 
  130.  5  - verification requires an output file
  131.  31 - could not open old file
  132.  32 - problem rewinding old file
  133.  33 - old file is empty
  134.  34 - unable to read entire oldfile into memory
  135.  35 - unable to allocate memory while creating synopsis
  136.  36 - verification failure
  137.  37 - unable to open temporary file
  138.  41 - problem allocating memory to create diff file
  139.  42 - problem opening newfile
  140.  43 - internal write problem
  141.  46 - error writing to ouptut file
  142.  47 - problem allocating memory to read newfile 
  143.  48 - problem reading newfile (possibly eof)
  144.  49 - unable to open output file
  145.  51 - unable to open "difference file" 
  146.  52 - not a gdiff formatted difference file
  147.  53 - unable to read from difference file
  148.  54 - unimplemented "large move" gdiff command encountered
  149.  55 - error in ungdiff procedure 
  150.  56 - illegal gdiff code
  151.  
  152. For example, you could use a REXX call of:
  153.  oldfile='old_version_of_a_file'   /*
  154.  newfile='new_version_of_a_file'
  155.  dif_file='difference_file_to_create'
  156.  address cmd 'GDIFF  -1 'oldfile'  'newfile' 'dif_file 
  157.  if rc<>0 then say "GDIFF failue with code= 'rc
  158.  
  159.  
  160.                         ---------------------
  161.  
  162. Disclaimer:
  163.  
  164.    This is freeware that is to be used at your own risk -- the 
  165.    author and any potentially affiliated institutions disclaim all 
  166.    responsibilties for any consequence arising from the use, misuse, or abuse 
  167.    of this software (or pieces of this software).
  168.  
  169.    You may use this (or subsets of this) program as you see fit,    
  170.    including for commercial purposes; so long as  proper attribution
  171.    is made, and so long as such use does not in any way preclude 
  172.    others from making use of this code.
  173.  
  174. Contact:
  175.  
  176.    Daniel Hellerstein (danielh@crosslink.net or danielh@econ.ag.gov)
  177.    
  178.  
  179.