helpers: truncate_and_unlink doc

src/borg/helpers.py

@@ -1996,6 +1996,17 @@ def secure_erase(path):
 
 
 def truncate_and_unlink(path):
+    """
+    Truncate and then unlink *path*.
+
+    Do not create *path* if it does not exist.
+    Open *path* for truncation in r+b mode (=O_RDWR|O_BINARY).
+
+    Use this when deleting potentially large files when recovering
+    from a VFS error such as ENOSPC. It can help a full file system
+    recover. Refer to the "File system interaction" section
+    in repository.py for further explanations.
+    """
     with open(path, 'r+b') as fd:
         fd.truncate()
     os.unlink(path)

src/borg/repository.py

@@ -1158,7 +1158,6 @@ class LoggedIO:
         self.segment = transaction_id + 1
         for segment, filename in self.segment_iterator(reverse=True):
             if segment > transaction_id:
-                # Truncate segment files before unlink(). This can help a full file system recover.
                 truncate_and_unlink(filename)
             else:
                 break
@@ -1234,12 +1233,7 @@ class LoggedIO:
         if segment in self.fds:
             del self.fds[segment]
         try:
-            filename = self.segment_filename(segment)
+            truncate_and_unlink(self.segment_filename(segment))
-            # Truncate segment files before unlink(). This can help a full file system recover.
-            # In this instance (cf. cleanup()) we need to use r+b (=O_RDWR|O_BINARY) and
-            # issue an explicit truncate() to avoid creating a file
-            # if *segment* did not exist in the first place.
-            truncate_and_unlink(filename)
         except FileNotFoundError:
             pass