improving design of the tool after thomas input

diff --git a/docs/design.py b/docs/design.py
index 5faa716..df55ee5 100644 (file)
--- a/docs/design.py
+++ b/docs/design.py
@@ -4,10 +4,33 @@ Backup Files Index format:
  * it will contain one line per file in the directory, even if the file didn't
    change. This way we can restore a diff backup without needing previous diffs.
 
-{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 0, "offset": 0}
-{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 0, "offset": 56464}
+
+{"type": "python-delta-tar-index", version: "1" }
+{"type": "BEGIN-FILE-LIST"}
+{"type": "directory", "path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 0, "offset": 0}
+{"type": "file", "path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 0, "offset": 0}
+{"type": "file", "path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 0, "offset": 56464}
 [...]
-{"path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 1, "offset": 0}
+{"type": "file", "path": value, "stat.st_mode": value, "mtime": value, "ctime": value, "uid": value, "gid": value, "inode": value, "size": value, "volume": 1, "offset": 0}
+{"type": "END-FILE-LIST"}
+{"type": "file-list-checksum", "checksum": "4327847432743278943278942" }
+(future additional fields)
+
+This is an extensible format. The first line indicates that this is a
+python-delta-tar-index, and the version. Then there's the file list and the
+checksum of the file list. After that, nothing else is currently defined but
+new extra fields could be defined in the future.
+
+The items inside of the file list are usually of type "directory" or "file":
+ * The "path" field of a directory points to the relative path to the backup
+   directory, for example "mbox/m/marina" if the backup dir is "/var/mail/".
+   The complete restore path would be "/var/mail/mbox/m/marina".
+ * The "path" field of a file points to the filename of the file in the
+   previous directory marker. For example "marina.dat" could be inside
+   "mbox/m/marina/" and the complete restore path could be
+   "/var/mail/mbox/m/marina/marina.dat".
+ * When a file is going to be removed, it will be prepended with "del:/" and
+   the file will have no offset set.
 
 DeltaTar proposed backup directory structure is quite simple:
 
@@ -35,7 +58,7 @@ class DeltaTar(object):
 
     def __init__(self, excluded_files=[], max_volume_size,
                  included_files=[], filter_func=None, mode="tar",
-                 password=None, log_path=None, index_encrypted=True,
+                 password=None, logger=None, index_encrypted=True,
                  index_name_func=None, volume_name_func=None):
         '''
         Constructor. Configures the diff engine.
@@ -57,7 +80,7 @@ class DeltaTar(object):
 
         - password: used together with aes modes to encrypt and decrypt backups.
 
-        - log_path: creates the backup log in this path.
+        - logger: python logger object. Not required.
 
         - index_encrypted: whether the index should be encrypted or not. Only
           makes sense to set it as True if mode includes aes128 or aes256.
@@ -98,7 +121,7 @@ class DeltaTar(object):
         '''
         pass
 
-    def restore_backup(self, target_path, backup_indexes_paths=[]):
+    def restore_backup(self, target_path, backup_indexes_paths=[], backup_tar_path=None):
         '''
         Restores a backup.
 
@@ -108,6 +131,12 @@ class DeltaTar(object):
         - backup_indexes_paths: path to backup indexes, in descending date order.
           The indexes indicate the location of their respective backup volumes,
           and multiple indexes are needed to be able to restore diff backups.
+          Note that this is an optional parameter: if not suplied, it will
+          try to restore directly from backup_tar_path.
+        - backup_tar_path: path to the backup tar file. Used as an alternative
+          to backup_indexes_paths to restore directly from a tar file without
+          using any file index. If it's a multivol tarfile, volume_name_func
+          will be called.
         '''
         pass