RDIFF-BACKUP(1)                  User Manuals                  RDIFF-BACKUP(1)


       rdiff-backup - local/remote mirror and incremental backup


       rdiff-backup      [options]      [[[user@]host1.foo]::source_directory]

       rdiff-backup  {{  -l  |  --list-increments  }   |   --remove-older-than
       time_interval  |  --list-at-time  time  |  --list-changed-since  time |
       --list-increment-sizes   |   --verify    |    --verify-at-time    time}

       rdiff-backup --calculate-average statfile1 statfile2 ...

       rdiff-backup           --test-server           [user1]@host1.net1::path
       [[user2]@host2.net2::path] ...


       rdiff-backup is a script, written in python(1) that backs up one direc-
       tory  to  another.  The target directory ends up a copy (mirror) of the
       source directory, but extra reverse diffs are stored in a special  sub-
       directory of that target directory, so you can still recover files lost
       some time ago.  The idea is to combine the best features  of  a  mirror
       and  an incremental backup.  rdiff-backup also preserves symlinks, spe-
       cial files, hardlinks, permissions, uid/gid ownership, and modification

       rdiff-backup  can  also  operate in a bandwidth efficient manner over a
       pipe, like rsync(1).  Thus you can use ssh and rdiff-backup to securely
       back  a  hard  drive  up to a remote location, and only the differences
       will be transmitted.  Using the default settings, rdiff-backup requires
       that the remote system accept ssh connections, and that rdiff-backup is
       installed in the user's PATH on the remote system.  For information  on
       other options, see the section on REMOTE OPERATION.

       Note  that  you  should  not  write to the mirror directory except with
       rdiff-backup.  Many of the increments are stored as reverse  diffs,  so
       if  you  delete  or  modify a file, you may lose the ability to restore
       previous versions of that file.

       Finally, this man page is intended more as a precise description of the
       behavior  and  syntax of rdiff-backup.  New users may want to check out
       the examples.html file included in the rdiff-backup distribution.


       -b, --backup-mode
              Force backup mode even if first argument appears to be an incre-
              ment or mirror file.

              Enter  calculate average mode.  The arguments should be a number
              of statistics files.  rdiff-backup will print the average of the
              listed statistics files and exit.

              Enable backup of MacOS X carbonfile information.

              If an rdiff-backup session fails, running rdiff-backup with this
              option on the destination dir will undo  the  failed  directory.
              This happens automatically if you attempt to back up to a direc-
              tory and the last backup failed.

              This is equivalent to '--compare-at-time now'

       --compare-at-time time
              Compare a directory with the backup set at the given time.  This
              can  be  useful  to  see  how archived data differs from current
              data, or to check that a backup is current.  This only  compares
              metadata,  in  the  same way rdiff-backup decides whether a file
              has changed.

              This is equivalent to '--compare-full-at-time now'

       --compare-full-at-time time
              Compare a directory with the backup set at the given  time.   To
              compare regular files, the repository data will be copied in its
              entirety to the source side and compared byte by byte.  This  is
              the slowest but most complete compare option.

              This is equivalent to '--compare-hash-at-time now'

       --compare-hash-at-time time
              Compare a directory with the backup set at the given time.  Reg-
              ular files will be compared by computing their  SHA1  digest  on
              the  source  side and comparing it to the digest recorded in the

              Normally only the final directory of the destination  path  will
              be  created  if it does not exist. With this option, all missing
              directories on the destination path will be  created.  Use  this
              option  with  care:  if  there is a typo in the remote path, the
              remote filesystem could fill up  very  quickly  (by  creating  a
              duplicate backup tree). For this reason this option is primarily
              aimed at scripts which automate backups.

       --current-time seconds
              This option is useful mainly for testing.  If set,  rdiff-backup
              will  use  it  for  the  current  time instead of consulting the
              clock.  The argument is the number of seconds since the epoch.

       --exclude shell_pattern
              Exclude the file or files matched by shell_pattern.  If a direc-
              tory  is  matched,  then files under that directory will also be
              matched.  See the FILE SELECTION section for more information.

              Exclude all device files.  This can be useful for  security/per-
              missions reasons or if rdiff-backup is not handling device files

              Exclude all fifo files.

       --exclude-filelist filename
              Excludes the files listed in filename.  If filename is handwrit-
              ten  you probably want --exclude-globbing-filelist instead.  See
              the FILE SELECTION section for more information.

              Like --exclude-filelist, but the list of files will be read from
              standard  input.  See the FILE SELECTION section for more infor-

       --exclude-globbing-filelist filename
              Like --exclude-filelist but each line of the  filelist  will  be
              interpreted  according  to  the  same  rules  as  --include  and

              Like --exclude-globbing-filelist, but the list of files will  be
              read from standard input.

              Exclude  files  on  file  systems  (identified by device number)
              other than the file system the root of the source  directory  is

       --exclude-regexp regexp
              Exclude  files  matching the given regexp.  Unlike the --exclude
              option, this option does not  match  files  in  a  directory  it
              matches.  See the FILE SELECTION section for more information.

              Exclude all device files, fifo files, socket files, and symbolic

              Exclude all socket files.

              Exclude all symbolic links. This option is automatically enabled
              if the backup source is running on native Windows to avoid back-
              ing-up NTFS reparse points.

       --exclude-if-present filename
              Exclude directories if filename is present. This option needs to
              come before any other include or exclude options.

              Authorize  a more drastic modification of a directory than usual
              (for instance, when overwriting of a destination path,  or  when
              removing  multiple  sessions  with --remove-older-than).  rdiff-
              backup will generally tell you if it needs this.   WARNING:  You
              can cause data loss if you mis-use this option.  Furthermore, do
              NOT use this option when doing a  restore,  as  it  will  DELETE
              FILES, unless you absolutely know what you are doing.

       --group-mapping-file filename
              Map  group  names  and  ids according the the group mapping file
              filename.  See the USERS AND GROUPS section  for  more  informa-

       --include shell_pattern
              Similar  to --exclude but include matched files instead.  Unlike
              --exclude, this option will also  match  parent  directories  of
              matched  files  (although  not necessarily their contents).  See
              the FILE SELECTION section for more information.

       --include-filelist filename
              Like --exclude-filelist, but include the listed  files  instead.
              If filename is handwritten you probably want --include-globbing-
              filelist instead.  See  the  FILE  SELECTION  section  for  more

              Like  --include-filelist,  but  read  the list of included files
              from standard input.

       --include-globbing-filelist filename
              Like --include-filelist but each line of the  filelist  will  be
              interpreted  according  to  the  same  rules  as  --include  and

              Like --include-globbing-filelist, but the list of files will  be
              read from standard input.

       --include-regexp regexp
              Include  files  matching  the  regular  expression regexp.  Only
              files explicitly matched by regexp  will  be  included  by  this
              option.  See the FILE SELECTION section for more information.

              Include all device files, fifo files, socket files, and symbolic

              Include all symbolic links.

       --list-at-time time
              List the files in the archive that were  present  at  the  given
              time.  If a directory in the archive is specified, list only the
              files under that directory.

       --list-changed-since time
              List the files that have changed in  the  destination  directory
              since  the given time.  See TIME FORMATS for the format of time.
              If a directory in the archive is specified, list only the  files
              under  that  directory.   This  option  does not read the source
              directory; it is used to compare the contents of  two  different
              rdiff-backup sessions.

       -l, --list-increments
              List  the  number  and  date of partial incremental backups con-
              tained in the specified destination  directory.   No  backup  or
              restore will take place if this option is given.

              List  the  total  size  of all the increment and mirror files by
              time.  This may be helpful in deciding how  many  increments  to
              keep,  and  when to --remove-older-than.  Specifying a subdirec-
              tory is allowable; then only the sizes of the mirror and  incre-
              ments pertaining to that subdirectory will be listed.

       --max-file-size size
              Exclude files that are larger than the given size in bytes

       --min-file-size size
              Exclude files that are smaller than the given size in bytes

              Exit  with  error instead of dropping acls or acl entries.  Nor-
              mally this may happen (with a warning) because  the  destination
              does  not  support them or because the relevant user/group names
              do not exist on the destination side.

              No Access Control Lists - disable backup of ACLs

              Disable backup of MacOS X carbonfile information

              This option prevents rdiff-backup  from  flagging  a  hardlinked
              file  as  changed  when  its device number and/or inode changes.
              This option is useful in situations where the source  filesystem
              lacks  persistent  device  and/or inode numbering.  For example,
              network filesystems may have mount-to-mount differences in their
              device  number  (but  possibly  stable  inode numbers); USB/1394
              devices may come up at different  device  numbers  each  remount
              (but  would  generally  have  same  inode number); and there are
              filesystems which don't even have the same  inode  numbers  from
              use to use.  Without the option rdiff-backup may generate unnec-
              essary numbers of tiny diff files.

              Disable the default gzip compression of most  of  the  .snapshot
              and .diff increment files stored in the rdiff-backup-data direc-
              tory.  A backup volume can contain compressed  and  uncompressed
              increments, so using this option inconsistently is fine.

       --no-compression-regexp  regexp
              Do  not compress increments based on files whose filenames match
              regexp.  The default includes many common  audiovisual  and  ar-
              chive files, and may be found in Globals.py.

              No Extended Attributes support - disable backup of EAs.

              This  will  disable  writing  to the file_statistics file in the
              rdiff-backup-data directory.   rdiff-backup  will  run  slightly
              quicker and take up a bit less space.

              Don't  replicate  hard links on destination side.  If many hard-
              linked files are present, this option can  drastically  decrease
              memory  usage.   This option is enabled by default if the backup
              source or restore destination is running on native Windows.

              Use nulls (\0) instead of  newlines  (\n)  as  line  separators,
              which  may help when dealing with filenames containing newlines.
              This affects the expected format of the files specified  by  the
              --{include|exclude}-filelist[-stdin]  switches  as  well  as the
              format of the directory statistics file.

              If set, rdiff-backup's output will be tailored for easy  parsing
              by computers, instead of convenience for humans.  Currently this
              only applies when listing increments using  the  -l  or  --list-
              increments  switches,  where  the  time will be given in seconds
              since the epoch.

              If the filesystem to which we are backing up is not  case-sensi-
              tive,  automatic  'quoting' of characters occurs. For example, a
              file 'Developer.doc' will be converted into  ';068eveloper.doc'.
              To override this behavior, you need to specify this option.

              If  set,  rdiff-backup will preserve uids/gids instead of trying
              to preserve unames and gnames.  See the USERS AND GROUPS section
              for more information.

              If  set,  summary  statistics will be printed after a successful
              backup.  If not set, this information will  still  be  available
              from  the  session  statistics file.  See the STATISTICS section
              for more information.

       -r, --restore-as-of restore_time
              Restore the specified directory as it was  as  of  restore_time.
              See  the TIME FORMATS section for more information on the format
              of restore_time, and see the RESTORING section for more informa-
              tion on restoring.

       --remote-cmd cmd
              Deprecated. Please use --remote-schema instead

       --remote-schema schema
              Specify  an alternate method of connecting to a remote computer.
              This is necessary to get rdiff-backup not to use ssh for  remote
              backups, or if, for instance, rdiff-backup is not in the PATH on
              the remote side.  See the  REMOTE  OPERATION  section  for  more

       --remote-tempdir path
              Adds  the  --tempdir  option  with  argument  path when invoking
              remote instances of rdiff-backup.

       --remove-older-than time_spec
              Remove the incremental backup  information  in  the  destination
              directory  that  has  been  around  longer  than the given time.
              time_spec can be either an absolute time, like "2002-01-04",  or
              a  time  interval.   The time interval is an integer followed by
              the character s, m, h, D, W, M, or Y, indicating  seconds,  min-
              utes,  hours,  days,  weeks, months, or years respectively, or a
              number of these concatenated.  For example, 32m  means  32  min-
              utes,  and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 sec-
              onds.  In this context, a month means 30 days,  a  year  is  365
              days, and a day is always 86400 seconds.

              rdiff-backup  cannot remove-older-than and back up or restore in
              a single session.  In order  to  both  backup  a  directory  and
              remove old files in it, you must run rdiff-backup twice.

              By  default,  rdiff-backup will only delete information from one
              session at a time.  To remove two or more sessions at  the  same
              time,  supply  the --force option (rdiff-backup will tell you if
              --force is required).

              Note that snapshots of deleted files are covered by this  opera-
              tion.  Thus if you deleted a file two weeks ago, backed up imme-
              diately afterwards, and then  ran  rdiff-backup  with  --remove-
              older-than  10D  today,  no  trace  of  that  file would remain.
              Finally, file selection options such as --include and  --exclude
              don't affect --remove-older-than.

       --restrict path
              Require  that  all  file  access be inside the given path.  This
              switch, and the following two, are intended to be used with  the
              --server  switch  to  provide  a  bit more protection when doing
              automated remote backups.  They are not intended  as  your  only
              line  of  defense  so please don't do something silly like allow
              public access to an rdiff-backup  server  run  with  --restrict-

       --restrict-read-only path
              Like --restrict, but also reject all write requests.

       --restrict-update-only path
              Like --restrict, but only allow writes as part of an incremental
              backup.  Requests for  other  types  of  writes  (for  instance,
              deleting path) will be rejected.

              Enter  server mode (not to be invoked directly, but instead used
              by another rdiff-backup process on a remote computer).

              When running ssh, do not use the -C option  to  enable  compres-
              sion.   --ssh-no-compression  is  ignored  if  you specify a new
              schema using --remote-schema.

       --tempdir path
              Sets the directory that rdiff-backup uses for temporary files to
              the  given path. The environment variables TMPDIR, TEMP, and TMP
              can also be used to set the temporary files directory.  See  the
              documentation  of  the  Python tempfile module for more informa-

       --terminal-verbosity [0-9]
              Select which messages will be displayed  to  the  terminal.   If
              missing the level defaults to the verbosity level.

              Test  for  the  presence  of a compatible rdiff-backup server as
              specified in  the  following  host::filename  argument(s).   The
              filename section will be ignored.

              Create timestamps in which the hour/minute/second separator is a
              - (hyphen) instead of a : (colon). It is safe to use this option
              on one backup, and then not use it on another; rdiff-backup sup-
              ports the intermingling of  different  timestamp  formats.  This
              option is enabled by default on platforms which require that the
              colon be escaped.

       --user-mapping-file filename
              Map user names and ids according to the user mapping file  file-
              name.  See the USERS AND GROUPS section for more information.

       -v[0-9], --verbosity [0-9]
              Specify  verbosity level (0 is totally silent, 3 is the default,
              and 9 is noisiest).  This determines how much is written to  the
              log file.

              This is short for --verify-at-time now

       --verify-at-time now
              Check  all  the data in the repository at the given time by com-
              puting the SHA1 hash of all the regular files and comparing them
              with the hashes stored in the metadata file.

       -V, --version
              Print the current version and exit


       There are two ways to tell rdiff-backup to restore a file or directory.
       Firstly, you can run rdiff-backup on a mirror file and use  the  -r  or
       --restore-as-of  options.   Secondly,  you  can  run it on an increment

       For example, suppose in the past you have run:

              rdiff-backup /usr /usr.backup

       to back up the /usr directory into the /usr.backup directory,  and  now
       want  a  copy  of  the  /usr/local  directory the way it was 3 days ago
       placed at /usr/local.old.

       One way to do this is to run:

              rdiff-backup -r 3D /usr.backup/local /usr/local.old

       where above the "3D" means 3 days (for other ways to specify the  time,
       see  the  TIME  FORMATS  section).  The /usr.backup/local directory was
       selected, because that is the directory containing the current  version
       of /usr/local.

       Note that the option to --restore-as-of always specifies an exact time.
       (So "3D" refers to the instant 72 hours before the present.)  If  there
       was  no  backup  made  at  that  time,  rdiff-backup restores the state
       recorded for the previous backup.  For instance, in the above case,  if
       "3D"  is  used,  and there are only backups from 2 days and 4 days ago,
       /usr/local as it was 4 days ago will be restored.

       The second way to restore  files  involves  finding  the  corresponding
       increment  file.   It  would be in the /backup/rdiff-backup-data/incre-
       ments/usr  directory,  and   its   name   would   be   something   like
       "local.2002-11-09T12:43:53-04:00.dir"  where  the  time indicates it is
       from 3 days ago.  Note that the increment files  all  end  in  ".diff",
       ".snapshot",  ".dir",  or  ".missing", where ".missing" just means that
       the file didn't exist at that time (finally, some of these may be gzip-
       compressed, and have an extra ".gz" to indicate this).  Then running:

              rdiff-backup                    /backup/rdiff-backup-data/incre-
              ments/usr/local.<time>.dir /usr/local.old

       would also restore the file as desired.

       If you are not sure exactly which version of a file  you  need,  it  is
       probably  easiest  to  either  restore  from  the  increments  files as
       described immediately above, or to see which increments  are  available
       with   -l/--list-increments,   and   then   specify  exact  times  into


       rdiff-backup uses time strings in two  places.   Firstly,  all  of  the
       increment  files rdiff-backup creates will have the time in their file-
       names in  the  w3  datetime  format  as  described  in  a  w3  note  at
       http://www.w3.org/TR/NOTE-datetime.     Basically    they   look   like
       "2001-07-15T04:09:38-07:00", which  means  what  it  looks  like.   The
       "-07:00" section means the time zone is 7 hours behind UTC.

       Secondly, the -r, --restore-as-of, and --remove-older-than options take
       a time string, which can be given in any of several formats:

       1.     the string "now" (refers to the current time)

       2.     a sequences of digits, like "123456890" (indicating the time  in
              seconds after the epoch)

       3.     A string like "2002-01-25T07:00:00+02:00" in datetime format

       4.     An interval, which is a number followed by one of the characters
              s, m, h, D, W, M, or  Y  (indicating  seconds,  minutes,  hours,
              days, weeks, months, or years respectively), or a series of such
              pairs.  In this case the string refers to the time that preceded
              the  current  time by the length of the interval.  For instance,
              "1h78m" indicates the time that was one hour and 78 minutes ago.
              The calendar here is unsophisticated: a month is always 30 days,
              a year is always 365 days, and a day is always 86400 seconds.

       5.     A date format of the form YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, or
              MM-DD-YYYY,  which  indicates  midnight  on the day in question,
              relative  to  the  current  timezone  settings.   For  instance,
              "2002/3/5",  "03-05-2002",  and  "2002-3-05" all mean March 5th,

       6.     A backup session specification which is a  non-negative  integer
              followed  by  'B'.  For instance, '0B' specifies the time of the
              current mirror, and '3B' specifies the time of  the  3rd  newest


       In order to access remote files, rdiff-backup opens up a pipe to a copy
       of rdiff-backup running on the remote machine.  Thus rdiff-backup  must
       be  installed  on  both  ends.   To  open this pipe, rdiff-backup first
       splits the filename  into  host_info::pathname.   It  then  substitutes
       host_info into the remote schema, and runs the resulting command, read-
       ing its input and output.

       The default remote schema is 'ssh -C %s  rdiff-backup  --server'  where
       host_info   is   substituted   for   '%s'.   So  if  the  host_info  is
       user@host.net, then rdiff-backup runs 'ssh  user@host.net  rdiff-backup
       --server'.  Using --remote-schema, rdiff-backup can invoke an arbitrary
       command in order to open up a remote pipe.  For instance,
              rdiff-backup --remote-schema 'cd  /usr;  %s'  foo  'rdiff-backup
       is basically equivalent to (but slower than)
              rdiff-backup foo /usr/bar

       Concerning  quoting, if for some reason you need to put two consecutive
       colons in the host_info section of a host_info::pathname  argument,  or
       in  the pathname of a local file, you can quote one of them by prepend-
       ing a backslash.  So in 'a\::b::c', host_info is 'a::b' and  the  path-
       name  is  'c'.   Similarly,  if you want to refer to a local file whose
       filename contains two consecutive colons, like 'strange::file',  you'll
       have  to  quote  one of the colons as in 'strange\::file'.  Because the
       backslash is a quote character in these circumstances, it too  must  be
       quoted  to  get  a  literal  backslash,  so  'foo\::\\bar' evaluates to
       'foo::\bar'.  To make things more complicated, because the backslash is
       also  a  common shell quoting character, you may need to type in '\\\\'
       at the shell prompt to get a literal backslash (if it  makes  you  feel
       better,  I  had  to  type  in  8  backslashes  to  get that in this man
       page...).  And finally, to include a literal % in the string  specified
       by --remote-schema, quote it with another %, as in %%.

       Although  ssh  itself  may be secure, using rdiff-backup in the default
       way presents some security risks.  For instance if the server is run as
       root, then an attacker who compromised the client could then use rdiff-
       backup to overwrite arbitrary server files by "backing up"  over  them.
       Such  a  setup  can be made more secure by using the sshd configuration
       option  command="rdiff-backup  --server"  possibly   along   with   the
       --restrict* options to rdiff-backup.  For more information, see the web
       page, the wiki, and the entries for the --restrict* options on this man


       rdiff-backup has a number of file selection options.  When rdiff-backup
       is run, it searches through the given source directory and backs up all
       the  files  matching  the specified options.  This selection system may
       appear complicated, but it is supposed to be flexible and  easy-to-use.
       If you just want to learn the basics, first look at the selection exam-
       ples in the examples.html file included in the package, or on  the  web
       at http://rdiff-backup.nongnu.org/examples.html

       rdiff-backup's  selection  system  was originally inspired by rsync(1),
       but there are many differences.  (For  instance,  trailing  backslashes
       have no special significance.)

       The  file  selection system comprises a number of file selection condi-
       tions, which are set using one of the following command  line  options:
       --exclude, --exclude-filelist, --exclude-device-files, --exclude-fifos,
       --exclude-sockets,    --exclude-symbolic-links,     --exclude-globbing-
       filelist,  --exclude-globbing-filelist-stdin, --exclude-filelist-stdin,
       --exclude-regexp,   --exclude-special-files,   --include,    --include-
       filelist,   --include-globbing-filelist,   --include-globbing-filelist-
       stdin,  --include-filelist-stdin,  and  --include-regexp.   Each   file
       selection  condition  either  matches or doesn't match a given file.  A
       given file is excluded by the file selection system  exactly  when  the
       first  matching  file  selection  condition  specifies that the file be
       excluded; otherwise the file is included.  When backing up, if  a  file
       is  excluded,  rdiff-backup  acts as if that file does not exist in the
       source directory.  When restoring, an excluded file is  considered  not
       to exist in either the source or target directories.

       For instance,

              rdiff-backup --include /usr --exclude /usr /usr /backup

       is exactly the same as

              rdiff-backup /usr /backup

       because  the  include  and  exclude  directives  match exactly the same
       files, and the --include comes first, giving it precedence.  Similarly,

              rdiff-backup  --include /usr/local/bin --exclude /usr/local /usr

       would backup the /usr/local/bin directory (and its contents),  but  not

       The  include, exclude, include-globbing-filelist, and exclude-globbing-
       filelist options accept extended shell globbing patterns.   These  pat-
       terns  can  contain  the special patterns *, **, ?, and [...].  As in a
       normal shell, * can be expanded to any string of  characters  not  con-
       taining "/", ?  expands to any character except "/", and [...]  expands
       to a single character of those characters specified (ranges are accept-
       able).   The  new special pattern, **, expands to any string of charac-
       ters whether or not it  contains  "/".   Furthermore,  if  the  pattern
       starts  with "ignorecase:" (case insensitive), then this prefix will be
       removed and any character in the string can be replaced with an  upper-
       or lowercase version of itself.

       If you need to match filenames which contain the above globbing charac-
       ters, they may be escaped using a backslash  "\".  The  backslash  will
       only  escape  the character following it so for ** you will need to use
       "\*\*" to avoid escaping it to the * globbing character.

       Remember that you may need to quote these characters when  typing  them
       into  a  shell,  so  the shell does not interpret the globbing patterns
       before rdiff-backup sees them.

       The --exclude pattern option matches a file iff:

       1.     pattern can be expanded into the file's filename, or

       2.     the file is inside a directory matched by the option.

       Conversely, --include pattern matches a file iff:

       1.     pattern can be expanded into the file's filename,

       2.     the file is inside a directory matched by the option, or

       3.     the file is a directory which contains a  file  matched  by  the

       For example,

              --exclude /usr/local

       matches /usr/local, /usr/local/lib, and /usr/local/lib/netscape.  It is
       the same as --exclude /usr/local --exclude '/usr/local/**'.

              --include /usr/local

       specifies    that     /usr,     /usr/local,     /usr/local/lib,     and
       /usr/local/lib/netscape  (but not /usr/doc) all be backed up.  Thus you
       don't have to worry about including parent  directories  to  make  sure
       that included subdirectories have somewhere to go.  Finally,

              --include ignorecase:'/usr/[a-z0-9]foo/*/**.py'

       would  match  a  file  like  /usR/5fOO/hello/there/world.py.  If it did
       match anything, it would also match /usr.  If there is no existing file
       that  the given pattern can be expanded into, the option will not match

       The --include-filelist,  --exclude-filelist,  --include-filelist-stdin,
       and --exclude-filelist-stdin options also introduce file selection con-
       ditions.  They direct rdiff-backup to read in  a  file,  each  line  of
       which  is  a file specification, and to include or exclude the matching
       files.  Lines are separated by newlines or nulls, depending on  whether
       the  --null-separator  switch  was  given.   Each line in a filelist is
       interpreted similarly to the way extended shell patterns  are,  with  a
       few exceptions:

       1.     Globbing patterns like *, **, ?, and [...]  are not expanded.

       2.     Include  patterns  do  not  match  files  in a directory that is
              included.  So /usr/local in  an  include  file  will  not  match

       3.     Lines  starting with "+ " are interpreted as include directives,
              even if found in a filelist  referenced  by  --exclude-filelist.
              Similarly,  lines  starting with "- " exclude files even if they
              are found within an include filelist.

       For example, if the file "list.txt" contains the lines:

              - /usr/local/doc
              + /var
              - /var

       then "--include-filelist list.txt" would include /usr, /usr/local,  and
       /usr/local/bin.        It       would      exclude      /usr/local/doc,
       /usr/local/doc/python,  etc.   It   neither   excludes   nor   includes
       /usr/local/man, leaving the fate of this directory to the next specifi-
       cation condition.  Finally, it is undefined what happens with /var.   A
       single file list should not contain conflicting file specifications.

       The --include-globbing-filelist and --exclude-globbing-filelist options
       also specify filelists, but each line in the filelist  will  be  inter-
       preted  as  a  globbing pattern the way --include and --exclude options
       are interpreted (although "+ " and "- " prefixing  is  still  allowed).
       For instance, if the file "globbing-list.txt" contains the lines:

              + dir/bar
              - **

       Then  "--include-globbing-filelist  globbing-list.txt" would be exactly
       the same as specifying "--include dir/foo --include  dir/bar  --exclude
       **" on the command line.

       Finally,  the  --include-regexp  and --exclude-regexp allow files to be
       included and excluded if their filenames match a python regular expres-
       sion.   Regular  expression  syntax is too complicated to explain here,
       but is covered in Python's library reference.  Unlike the --include and
       --exclude  options,  the  regular  expression options don't match files
       containing or contained in matched files.  So for instance

              --include '[0-9]{7}(?!foo)'

       matches any files whose full pathnames  contain  7  consecutive  digits
       which  aren't followed by 'foo'.  However, it wouldn't match /home even
       if /home/ben/1234567 existed.


       There can be complications preserving ownership  across  systems.   For
       instance  the  username  that  owns a file on the source system may not
       exist on the destination.  Here is how rdiff-backup maps  ownership  on
       the  source  to  the destination (or vice-versa, in the case of restor-

       1.     If the --preserve-numerical-ids  option  is  given,  the  remote
              files  will always have the same uid and gid, both for ownership
              and ACL entries.  This may cause unames and gnames to change.

       2.     Otherwise, attempt to preserve the user and group names for own-
              ership  and  in ACLs.  This may result in files having different
              uids and gids across systems.

       3.     If a name cannot be preserved (e.g. because  the  username  does
              not  exist), preserve the original id, but only in cases of user
              and group ownership.  For ACLs, omit any entry that  has  a  bad
              user or group name.

       4.     The  --user-mapping-file  and --group-mapping-file options over-
              ride this behavior.  If either of these options  is  given,  the
              policy described in 2 and 3 above will be followed, but with the
              mapped user and group instead of the original.  If  you  specify
              both  --preserve-numerical-ids  and  one of the mapping options,
              the behavior is undefined.

       The user and group mapping files both have the same form:


       Each line should contain a name or id, followed by a  colon  ":",  fol-
       lowed  by  another name or id.  If a name or id is not listed, they are
       treated in the default way described above.

       When restoring, the above behavior is also followed, but note that  the
       original  source  user/group  information  will  be  the input, not the
       already mapped user/group information present in the backup repository.
       For  instance,  suppose you have mapped all the files owned by alice in
       the source so that they are owned by ben in the repository, and now you
       want  to  restore,  making sure the files owned originally by alice are
       still owned by alice.  In this case there is no need to use any of  the
       mapping  options.   However, if you wanted to restore the files so that
       the files originally owned by alice on the source are now owned by ben,
       you  would  have  to use the mapping options, even though you just want
       the unames of the repository's files preserved in the restored files.


       Every session rdiff-backup saves various statistics into two files, the
       session    statistics    file    at   rdiff-backup-data/session_statis-
       tics.<time>.data and the directory  statistics  file  at  rdiff-backup-
       data/directory_statistics.<time>.data.   They  are  both text files and
       contain similar information: how many  files  changed,  how  many  were
       deleted,  the total size of increment files created, etc.  However, the
       session statistics file is  intended  to  be  very  readable  and  only
       describes  the  session  as  a whole.  The directory statistics file is
       more compact (and slightly less readable) but describes every directory
       backed up.  It also may be compressed to save space.

       Statistics-related  options include --print-statistics and --null-sepa-

       Also, rdiff-backup will save various messages to the log file, which is
       rdiff-backup-data/backup.log  for  backup  sessions  and  rdiff-backup-
       data/restore.log for restore sessions.  Generally what  is  written  to
       this  file  will  coincide  with  the  messages  displayed to stdout or
       stderr, although this can  be  changed  with  the  --terminal-verbosity

       The  log  file  is  not compressed and can become quite large if rdiff-
       backup is run with high verbosity.


       If rdiff-backup finishes successfully, the exit status will be  0.   If
       there  is  an unrecoverable (critical) error, it will be non-zero (usu-
       ally 1, but don't depend on this  specific  value).   When  setting  up
       rdiff-backup  to  run  automatically (as from cron(8) or similar) it is
       probably a good idea to check the exit code.


       The gzip library in versions 2.2 and earlier of python  (but  fixed  in
       2.3a1)  has  trouble producing files over 2GB in length.  This bug will
       prevent rdiff-backup from producing large compressed increments  (snap-
       shots  or  diffs).   A  workaround  is to disable compression for large
       uncompressable files.


       Ben Escoto <ben@emerose.org>

       Feel free to ask me questions or send me bug reports, but you may  want
       to see the web page, mentioned below, first.


       python(1),  rdiff(1), rsync(1), ssh(1).  The main rdiff-backup web page
       is at http://rdiff-backup.nongnu.org/.  It has more information,  links
       to the mailing list and CVS, etc.

Version 1.3.3                     MARCH 2009                   RDIFF-BACKUP(1)

Man(1) output converted with man2html