bc3 0.1.0

data/BCSS_Binary_Format.txt

@@ -0,0 +1,239 @@
+-------------------------------------------------------------------------------
+Beyond Compare Snapshot Format                                      Version 1.1
+-------------------------------------------------------------------------------
+
+Beyond Compare snapshots (.bcss) are binary files containing the file metadata
+(names, sizes, last modified times) of a directory structure without storing
+any of the file content.  They are designed to be read sequentially.  File
+record sizes are variable, so there's no way to seek to arbitrary records
+without reading all of the records before it.
+
+
+===========
+File Header
+===========
+
+Snapshots start with a fixed size header that contains an ID value, version
+information, a creation date, and various flags, optionally followed by the
+source folder's path:
+
+ - HEADER STRUCTURE -
+    [0..3]   = 'BCSS'
+    [4]      = Major version (UByte) 
+    [5]      = Minor version (UByte)
+    [6]	     = Minimum Supported Major Version (UByte)
+    [7]	     = Minimum Supported Minor Version (UByte)
+    [8..F]   = Creation Time (FileTime)
+    [10..11] = Flags         (UWord)
+
+            Bit : Meaning
+              0 : Compressed
+              1 : Source Path included
+              2 : Reserved
+              3 : UTF-8
+           4-15 : Reserved
+
+    [12..13] = Path Length (UWord)   | Optional
+    [14..N]  = Path        (char[])  |
+
+Version Information:
+    The first two version bytes represent the actual major and minor versions
+of the file, and reference a specific version of this specification.  The
+second pair of version bytes represent the minimum snapshot version which must
+be supported in order to read the snapshot file.  Version 1.1 can be read by
+Version 1.0 applications, so currently Major/Minor should be set to 1.1 and
+Minimum should be 1.0.
+
+Flags:
+    Compressed: If set everything following the header is compressed as a raw
+deflate stream, as defined by RFC 1951.  It is the same compression used by
+.zip and .gz archives.
+
+    Source Path included: If set the original folder's path is included
+immediately after the header.  This is only on part of the file besides the
+fixed header that is not compressed.
+
+    UTF-8: If set the snapshot was compressed on a system where the default
+character encoding is UTF-8 (Linux, OS X).  Filenames, paths, and link targets
+will all be stored as UTF-8.  If this isn't set the paths are stored using the
+original OS's ANSI codepage (Windows).  In that case any paths may be stored a
+second time as UTF-8 in extended headers.
+
+
+==========
+Data Types
+==========
+   
+UByte:
+    Unsigned 8-bit value
+
+UInt16:
+    Unsigned 16-bit value
+
+Int32:
+    Signed 32-bit value
+
+UInt32:
+    Unsigned 32-bit value
+
+Int64:
+    Signed 64-bit value
+
+char[]:
+    Variable length single-byte character array (ANSI or UTF-8).
+
+FileTime:
+    Windows FILETIME structure.  64-bit value representing the number of
+100-nanosecond intervals since January 1, 1601 UTC.  Stored in local time.
+
+ShortString:
+    Variable length single-byte character string (ANSI or UTF-8).   Not null
+terminated.
+
+    Length   : UByte
+    Data     : char[Length]
+
+FileExString:
+    Variable length single-byte character string (UTF-8).  See "File Extended
+Header" section for details.
+
+
+===============
+Content Records
+===============
+
+Immediately after the header the directory tree is stored as a series of
+records.  Directories are stored recursively: each one starts with the
+directory header, then any files and subdirectories (and their children), then
+the directory end record.
+
+The ID_DIRECTORY record for the outer most (source) folder is not stored, so
+the content stream actually starts with the first child, and continues until
+it finds an unmatched ID_END_REC record.  Anything following that is currently
+ignored.
+
+Each record starts with a single UByte ID value and then the data defined below.
+
+ID_DIRECTORY (0x01)
+    Represents a directory on the system, or an expanded archive file.
+
+    Name           : ShortString
+    Last Modified  : FileTime
+    DOS Attributes : UInt32
+
+
+ID_DIRECTORY_END (0xFF)
+    Represents the end of a directory listing.  No data.
+
+
+ID_FILE (0x02)
+    Represents a file on the system.  
+
+    Name           : ShortString
+    Last Modified  : FileTime
+    DOS Attributes : UInt32
+    Size           : Int32[+Int64]
+       If Size > 2GB, store as Int32(-1) followed by Int64
+    CRC32          : UInt32
+        
+
+ID_FILE_EX (0x03)
+    Represents a file on the system, with extended headers.
+    
+    Name..CRC32 is the same as ID_FILE
+    ExtraLen       : UInt16
+    ExtraData      : Byte[ExtraLen]
+
+
+ID_EXTENDED (0x04)
+    Extended headers
+
+    SubType        : UByte
+    Length         : UWord
+    Data           : Byte[Length]
+
+
+========================
+Extended Header Subtypes
+========================
+
+Extended headers should be written in ascending numeric order.  Once BC sees
+an extended subtype that it doesn't undertand it stops processing ID_EXTENDED
+headers until it finds one of ID_DIRECTORY/ID_DIRECTORY_END/ID_FILE/ID_FILE_EX.
+
+
+EX_UTF8 (0x01)
+    UTF-8 encoded filename for the ID_DIRECTORY that immediately preceeded
+this header.  The length is given in the ID_EXTENDED header and the data is a
+char[].
+    If the .bcss header flags indicate that the data is not UTF-8 and the
+source path is included this can be included as the first record in the file
+in order to give a UTF-8 version of the source path.
+
+
+EX_DIRECTORY_EX (0x02)
+    Extended directory header for the ID_DIRECTORY that immediately preceeded
+this header.  Data is the record below, but Length may be larger to support
+future expansion.
+
+    Flags         : UByte
+      Bit : Meaning
+        0 : Error - Contents not available.  Flag as a load error in BC.
+   
+
+EX_RESYNC (0x03)
+    Works around a bug in Beyond Compare's parser in versions prior to 3.2.2.
+If an ID_DIRECTORY is followed by any ID_EXTENDED headers besides EX_UTF8 or
+EX_DIRECTORY_EX include one copy of this header before them.
+
+    Length : UWord   = 0x0001
+    Data   : Byte[1] = 0
+
+
+EX_LINK_PATH (0x04)
+    UTF-8 encoded symbolic link path for the ID_DIRECTORY that immediately
+preceeded this header.  The length is given in the ID_EXTENDED header and the
+data is a char[].
+
+
+=====================
+File Extended Headers
+=====================
+
+Like extended headers, file extended headers should be written in ascending
+numeric order.
+
+FILE_EX_VERSION (0x01)
+    String representation of an executable file's Major/Minor/Maint/Build
+version (e.g., "2.11.28.3542").
+
+    Length : UByte
+    Data   : char[Length]
+
+
+FILE_EX_UTF8 (0x02)
+    UTF-8 encoded filename.  Stored as a FileExString.  Only used if the UTF-8
+name doesn't match the ANSI encoded one or if the filename is longer than 255
+characters.
+
+
+FILE_EX_LINK_PATH (0x03)
+    UTF-8 encoded symbolic link path.  Stored as a FileExString.
+
+
+FileExString
+------------
+Beyond Compare v2.4.1 and earlier will produce incorrect results if it
+encounters a raw 0x01 byte in a file extended header.  To prevent that most
+strings in ID_FILE_EX extended headers are written like so:
+
+    Length : UByte[+UByte]
+    Data   : char[Length]
+
+    If (Length <> 1) and (Length <= 127) then Length is 1 byte
+    Otherwise the Length is written as
+      Low  : UByte(Length) OR 0x80
+      High : UByte(Length shr 7) OR 0x80
+
+If an extended header must have a 0x01 in it (other than FILE_EX_VERSION),
+increase the .bcss header's Minimum Supported Version to 1.1.

data/bin/bc3_merge.rb

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+=begin rdoc
+bc3_merge.rb
+
+Merge snapshots and build a new snapshot with all files.
+
+Example:
+  bc3_merge.rb '*.bcss'
+Takes all snapshots in the directory and build a new one.
+
+=Options
+==Target snapshot
+The filename for the target snapshot will be compound by
+_snapshot_merge__ and a time stamp.
+
+You may choose your own name:
+  bc3_merge.rb *.bcss -t merged_snapshot.bcss
+
+==Folder for insertion
+If you add a snapshot, you must define, how you add the snapshot.
+
+Each snapshot has a source path, e.g. c:/user/me/folder1.
+There are three different possible behaviours how you 
+handle the source path of your snapshoot.
+
+Attention!
+When you use wildcards inside a shell, the may be expanded.
+To move the wildcards to the script, you must mask your input
+
+Wrong:
+  bc3_merge.rb -r *.bcss
+Correct:
+  bc3_merge.rb -r '*.bcss'
+
+===Full source path
+The full source path (starting from roor) will be added to the snapshot
+  bc3_merge.rb -r '*.bcss'
+or
+  bc3_merge.rb -root '*.bcss'
+
+===Add with base path
+The snapshot is added with the base directory name.
+
+With source path _c:/user/me/folder1_, the snapshot would be added as _folder1_
+
+  bc3_merge *.bcss
+or
+  bc3_merge -b '*.bcss'
+or
+  bc3_merge --base '*.bcss'
+
+===Add without source path info
+The snapshot is added directly to the target snapshot.
+There is no source path information used.
+
+  bc3_merge -i '*.bcss'
+or
+  bc3_merge --initial '*.bcss'
+
+=Usage Examples
+  bc3_merge.rb my_folder1.bcss my_folder1.bcss
+Takes the two snapshots and mix them.
+
+  bc3_merge.rb '*.bcss'
+Takes all snapshots in the directory and build a new one.
+=end
+
+require 'optparse'
+require 'bc3'
+#~ $log.level = Log4r::DEBUG
+
+#Collector
+$options = {
+  target: Time.now.strftime("snapshot_merge_%Y-%m-%d_%H-%M-%S.bcss"),
+  source: Dir.pwd,
+  root: [],
+  base: [],
+  initial: [],
+}
+
+=begin
+Create a Parser for command line
+=end
+opts = OptionParser.new()
+opts.banner = "Usage: bc3_merge.rb [options] [source snapshots]"	#Usage-zeile
+opts.separator("Merge Beyond Compare Snapshots to a new snapshot")	
+
+=begin
+Source path
+=end
+opts.on("-s", "--source  SOURCE", "Set source path for the snapshot") { |v|
+  $options[:source] = v
+}
+=begin
+Set target name.
+=end
+opts.on("-t", "--target  TARGET", "Set target file name") { |v|
+  $options[:target] = v
+}
+
+=begin
+Define source snapshots and how they are added.
+=end
+opts.on("-r", "--root    SNAPSHOT_MASK", "Add snapshots with root-information") { |v|
+  $options[:root] << v
+}
+
+opts.on("-b", "--base    SNAPSHOT_MASK", "Add snapshots with base-information") { |v|
+  $options[:base] << v
+}
+
+opts.on("-i", "--initial SNAPSHOT_MASK", "Add snapshots without source-information") { |v|
+  $options[:initial] << v
+}
+
+#Parsen der Parameter mit Exception bei ung�ltigen Parametern
+begin
+	opts.parse!
+# rescue OptionParser::MissingArgument => err
+# rescue OptionParser::InvalidOption => err
+rescue OptionParser::MissingArgument, OptionParser::InvalidOption => err
+	puts "Error:\t#{err}"
+	#Ausgabe der Schnittstelle
+	puts opts
+end
+
+snapshot = BC3::Snapshot.new( $options[:source] )
+
+$options[:root].each{|mask|
+  puts "Add #{mask} in root-mode"
+  Dir[mask].each{|file|
+    snap = BC3::SnapshotParser.new(file)
+    snapshot << folder = BC3::Folder.new( snap.snapshot.path, snap.timestamp)
+    snap.snapshot.each{|key, x| folder << x }
+  }
+}
+
+($options[:base] + ARGV).each{|mask|
+  puts "Add #{mask} in base-mode"
+  Dir[mask].each{|file|
+    snap = BC3::SnapshotParser.new(file)
+    snapshot << folder = BC3::Folder.new( File.basename(snap.snapshot.path), snap.timestamp )
+    snap.snapshot.each{|key, x| folder << x }
+  }
+}
+
+$options[:initial].each{|mask|
+  puts "Add #{mask} in raw-mode"
+  Dir[mask].each{|file|
+    BC3::SnapshotParser.new(file).snapshot.each{|key, x| snapshot << x }
+  }
+}
+
+#~ puts snapshot.each.keys
+snapshot.save($options[:target])

data/examples/test_combine.rb

@@ -0,0 +1,43 @@
+$:.unshift('../lib')
+require 'bc3'
+require 'yaml'
+
+  test = BC3::Snapshot.newh(YAML.load(<<data
+:snapshot: C:\\Temp
+:content: 
+- :dirname: dir1
+  :content: 
+  - :filename: file1.txt
+    :filesize: 32
+data
+))
+
+test << BC3::Folder.newh(YAML.load(<<data
+:dirname: dir3
+:content: 
+- :filename: file1.txt
+  :filesize: 32
+data
+))
+
+test << BC3::Folder.newh(YAML.load(<<data
+:dirname: dir3
+:content: 
+- :filename: file1.txt
+  :filesize: 32
+- :filename: file2.txt
+  :filesize: 12
+data
+))
+
+
+#~ puts test.to_hash.to_yaml#Hash falsch (keine Aggregation)
+test.save('results/test_combine_1.bcss')#bcss aggregiert selbst
+
+test << BC3::File.new( filename: 'dir2', filesize: 17 )
+
+test << BC3::File.new( filename: 'test.txt', filesize: 17 )
+test << BC3::File.new( filename: 'test.txt', filesize: 17 )
+
+puts test.to_hash.to_yaml#Hash falsch (keine Aggregation)
+test.save('results/test_combine_2.bcss')#bcss aggregiert selbst

data/examples/test_filesystem.rb

@@ -0,0 +1,6 @@
+$:.unshift('../lib')
+#Define directroy to be packed.
+dir = 'folder1'
+x = BC3::Snapshot.newd(dir)
+x.save("results/#{dir}_compressed.bcss", true)
+x.save("results/#{dir}_compressed.xxxx", true)