#!/bin/bash
#####
# Removes files from an rdiff-backup set.
#
# Deletes files and directories from the backup set, including the current
# mirror and all increments, and removes references from metadata files.
# In the metadata directory, log files, session_statistics files, and backup
# files (names ending with ~) are left as-is.
#
# FIXME -- Metadata for Mac resource forks is not handled,
#          long_filename_data is not handled.
#
#          If the same full pathname has, at various times, been used both for
#          a directory and for a non-directory, then removal of the
#          non-directory file will not be possible unless the "-R" option is
#          given to remove the directory and its contents as well.  See the
#          WARNING message below.
#
#          When removing some, but not all, of the links to a file with
#          multiple hard links, the link counts for the other hard links
#          should be adjusted.  That is extraordinarily difficult to do in a
#          metadata diff chain, and the consequences of not adjusting the
#          count are benign.  (Those link counts are already too high if not
#          all of the links to an inode were originally included in the backup
#          set.)
#
# The commented-out "touch -r ..." lines would implement a semi-"stealth"
# mode, in which the modified metadata files retain their original timestamps.
#####


Usage: rmv-from-backup [-DRrnk] backup_dir path_glob [path_glob ...]
       rmv-from-backup {-h|--help}
  -D         (Debug) Never delete the temp directory
  -k         Keep the backup copies of changed metadata files (needs a
             lot of space in the rdiff-backup-data directory).
  -R         Recursively delete directories matched by a path_glob
  -r         Limited recursion.  Allow a wildcard in the final
             portion of a path_glob to match both directory components
             and non-directories, but leave the directory structure
             intact.
  -n         Print commands that would be executed, but do nothing
  -h --help  Print full help.

Every path_glob must be absolute (begin with '/') and is rooted at
backup_dir.  The '.' character is NOT special in a path glob, and with
the "-R" or "-r" option netiher is '/', so "/xxx/foo*" would then match
all paths that begin with "/xxx/foo", including, for example,
"/xxx/foo23/dir1/dir2/somefile".

You do get a chance to review the list of files to be deleted and decide
whether to continue.  Generating the new metadata files can take a long
time, but that occurs in a temporary directory and can be safely
interrupted.  Once installation of the new files begins, the process
becomes non-interruptable.  If something does kill the process before it
completes, recovery can usually be accomplished re-running the exact
same command.