From 77300abd949c68b20df9c0d3d379f45aa427d149 Mon Sep 17 00:00:00 2001
From: Thomas Schmitt <scdbackup@gmx.net>
Date: Sat, 8 Mar 2008 12:27:22 +0000
Subject: [PATCH] Example use case for -update_r "Incremental backup of a few
 directory trees"

---
 xorriso/xorriso.1 | 87 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 78 insertions(+), 9 deletions(-)

diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1
index 35315d5c..52d70d69 100644
--- a/xorriso/xorriso.1
+++ b/xorriso/xorriso.1
@@ -45,6 +45,8 @@ Renames or deletes file objects in the ISO image.
 .br
 Changes file properties in the ISO image.
 .br
+Updates ISO subtrees incrementally to match given disk subtrees.
+.br
 Can write result as completely new image to optical media or
 filesystem objects.
 .br
@@ -1540,6 +1542,27 @@ Use text as this program's name and perform -help.
 .br
 .SH EXAMPLES
 .SS
+.B Overview of examples:
+As superuser learn about available drives
+.br
+Blank media and compose a new ISO image as batch run
+.br
+A dialog session doing about the same
+.br
+Manipulating an existing ISO image on the same media
+.br
+Copy modified ISO image from one media to another
+.br
+Write a ISO image into a pipe (single-session only)
+.br
+Perform a single session run as of cdrtools traditions
+.br
+Adjust thresholds for verbosity, exit value and program abort
+.br
+Examples of input timestrings
+.br
+Incremental backup of a few directory trees
+.SS
 .B As superuser learn about available drives
 Consider to give rw permissions to those users or groups
 which shall be able to use the drives with xorriso.
@@ -1691,6 +1714,15 @@ first and only session to the output drive.
 .br
  | gzip >image.iso.gz
 .SS
+.B Perform a single session run as of cdrtools traditions
+This shall illustrate how xorriso can act in either role.
+Between both processes there can be performed arbitrary transportation
+or filtering.
+.br
+\fB$\fR xorriso -as mkisofs -J -R /home/prepared_for_iso/tree | \\
+.br
+ xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -eject - 
+.SS
 .B Adjust thresholds for verbosity, exit value and program abort
 Be quite verbous, exit 32 if severity "FAILURE" was encountered,
 do not abort prematurely but forcibly go on until the end of commands.
@@ -1705,15 +1737,6 @@ do not abort prematurely but forcibly go on until the end of commands.
 .br
  ...
 .SS
-.B Perform a single session run as of cdrtools traditions
-This shall illustrate how xorriso can act in either role.
-Between both processes there can be performed arbitrary transportation
-or filtering.
-.br
-\fB$\fR xorriso -as mkisofs -J -R /home/prepared_for_iso/tree | \\
-.br
- xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -eject - 
-.SS
 .B Examples of input timestrings
 .br
 As printed by program date:
@@ -1736,6 +1759,52 @@ Three hours ago:
 .br
 Seconds since Jan 1 1970:
 .B =1194531416
+.SS
+.B Incremental backup of a few directory trees
+This does the following to directories /open_source_project and /personal_mail
+in the ISO image:
+create them if not existing yet,
+compare them with their disk counterparts,
+add disk file objects which are missing yet,
+overwrite those which are different on disk,
+and delete those which have vanished on disk.
+.br
+\fB$\fR xorriso -dev /dev/sr0 \\
+.br
+ -update_r /home/thomas/open_source_projects /open_source_projects \\
+.br
+ -update_r /home/thomas/personal_mail /personal_mail \\
+.br
+ -commit_eject all
+.br
+To be used several times on the same media, whenever an update of
+the two disk trees to the media is desired. Begin with blank media and start
+a new blank media when the run fails due to lack of remaining space on
+the old one.
+.br
+This makes most sense with backups on non-erasable media like CD-R,
+DVD-R, DVD+R if the full backup leaves substantial remaining capacity
+on media and if the expected changes are much smaller than the full backup.
+An update run will probably save no time but last longer than a full backup.
+.br 
+With overwriteable media like DVD+RW or disk files, the older backup versions
+cannot be retrieved. But with multi-session media and mount option "session="
+it is possible to access the session trees which represent the older backup
+versions. 
+.br
+\fBDo not write more than about 50 sessions\fR to one multi-session media.
+Theoretical limits are higher but in practice the media deteriorate more early.
+It might also be that your operating system has a session limit with mount.
+Always have a blank media ready to perform a full backup in case the update
+attempt fails.
+.br 
+If you have enough re-useable media for a round-robin scheme then better do
+full backups with blank media each time. Blanking can be achieved by
+either a separate run:
+.br
+\fB$\fR xorriso -outdev /dev/sr0 -blank fast -eject all
+.br
+or in the update run by using option -blank "fast" before option -update_r.
 .br
 .SH FILES
 .SS