Document restore code index handling

diff --git a/deltatar/deltatar.py b/deltatar/deltatar.py
index a01e3bb..0edc28a 100644 (file)
--- a/deltatar/deltatar.py
+++ b/deltatar/deltatar.py
@@ -809,7 +809,7 @@ class DeltaTar(object):
             # if the file is in both iterators, it means it might have either
             # not changed (in which case we will just list it in our index but
             # it will not be included in the tar file), or it might have
-            # changed, in which case we will list it.
+            # changed, in which case we will snapshot it.
             elif ipath and dpath:
                 if self._equal_stat_dicts(ipath, dpath):
                     action = 'list'
@@ -1259,6 +1259,7 @@ class DeltaTar(object):
                                    tarobj=index_it.tar_obj)
         elif mode == "diff":
             helper = RestoreHelper(self, cwd, backup_indexes_paths)
+            # get iterator from newest index at _data[0]
             index_it = self.iterate_index_path(helper._data[0]["path"])
 
         dir_it = self._recursive_walk_dir('.')
@@ -1455,7 +1456,7 @@ class RestoreHelper(object):
     def restore(self, itpath, l_no, callback=None):
         '''
         Restore the path from the appropiate backup. Receives the current path
-        from the first index iterator. itpath must be not null.
+        from the newest (=first) index iterator. itpath must be not null.
         callback is a custom function that gets called for every file.
         '''
         path = itpath['path']
@@ -1469,6 +1470,7 @@ class RestoreHelper(object):
             # all cases so we just need to finish
             return
 
+        # get data from newest index (_data[0])
         data = self._data[0]
         upath = self._deltatar.unprefixed(path)
 
@@ -1478,7 +1480,7 @@ class RestoreHelper(object):
             os.makedirs(parent_dir)
         parent_dir_mtime = int(os.stat(parent_dir).st_mtime)
 
-        # if path is found in the first index as to be snapshotted, deal with it
+        # if path is found in the newest index as to be snapshotted, deal with it
         # and finish
         if path.startswith('snapshot://'):
             self.restore_file(itpath, data, path, l_no, upath)
@@ -1489,6 +1491,10 @@ class RestoreHelper(object):
 
         # we go from index to index, finding the path in the index, then finding
         # the index with the most recent snapshot of the file being restored
+        #
+        # Right now we support diff backups, only. No incremental backups.
+        # As a result _data[0] is always the diff backup index
+        # and _data[1] the full backup index.
         if len(self._data) > 1:
             data = self._data[1]
             while True:
@@ -1505,6 +1511,8 @@ class RestoreHelper(object):
                                                 'one. Path was ignored and untouched.') % path)
                     return
                 elif cur_path.startswith('snapshot://'):
+                    # this code path is reached when the file is unchanged
+                    # in the newest index and therefore of type 'list://'
                     self.restore_file(d, data, path, l_no, dpath)
 
                     # now we restore parent_directory mtime