RDIFF-BACKUP-OLD(1)

💖 bestie, welcome to the old rdiff-backup manual — RDIFF-BACKUP-OLD(1), straight off the User Manuals shelf. It's deprecated, it's iconic, and we're gonna read it together. 🫶

---

🎀 NAME 🎀

rdiff-backup — local/remote mirror and incremental backup

---

✨ SYNOPSIS ✨

rdiff-backup [options...]  [[user@]host1.foo::]source_directory
[[user@]host2.foo::]destination_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}
[[user@]host2.foo::]destination_directory

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

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

---

💅 DESCRIPTION 💅

Okay so first things first, bestie: this man-page is describing the old deprecated version of the rdiff-backup command line. If you can, go read the new rdiff-backup(1) man-page instead. It's giving upgrade your life. ✨

rdiff-backup is a script written in python(1) that backs up one directory to another. The target directory ends up a copy (mirror) of the source directory, but extra reverse diffs are stored in a special subdirectory of that target directory, so you can still recover files lost some time ago. The whole point is combining the best features of a mirror and an incremental backup. And it also preserves symlinks, special files, hardlinks, permissions, uid/gid ownership, and modification times. Lowkey a whole package. 💖

rdiff-backup can also operate in a bandwidth efficient manner over a pipe, like rsync(1). So 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. With 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 info 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. No cap. 😭

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. 🦋

---

🌈 OPTIONS 🌈

• --allow-duplicate-timestamps — This option is only to be used if you encounter the issue of metadata mirrors with the same timestamp. In such cases, you may use this flag to first recover from the failed backup with something like rdiff-backup --allow-duplicate-timestamps --check-destination-dir <targetdir> after which you will need to remove those old duplicate entries using the --remove-older-than parameter.
• --api-version api — Sets the API version to the given integer between minimum and maximum versions. It is the responsibility of the user to make sure that this version is also supported by any server started by this client.
• -b, --backup-mode — Force backup mode even if first argument appears to be an increment or mirror file.
• --calculate-average — 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.
• --carbonfile — Enable backup of MacOS X carbonfile information.
• --check-destination-dir — 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 directory and the last backup failed.
• --compare — 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.
• --compare-full — 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.
• --compare-hash — 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. Regular files will be compared by computing their SHA1 digest on the source side and comparing it to the digest recorded in the metadata.
• --create-full-path — 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 directory is matched, then files under that directory will also be matched. See the FILE SELECTION section for more information.
• --exclude-device-files — Exclude all device files. This can be useful for security/permissions reasons or if rdiff-backup is not handling device files correctly.
• --exclude-fifos — Exclude all fifo files.
• --exclude-filelist filename — Excludes the files listed in filename. If filename is handwritten you probably want --exclude-globbing-filelist instead. See the FILE SELECTION section for more information.
• --exclude-filelist-stdin — Like --exclude-filelist, but the list of files will be read from standard input. See the FILE SELECTION section for more information.
• --exclude-globbing-filelist filename — Like --exclude-filelist but each line of the filelist will be interpreted according to the same rules as --include and --exclude.
• --exclude-globbing-filelist-stdin — Like --exclude-globbing-filelist, but the list of files will be read from standard input.
• --exclude-other-filesystems — Exclude files on file systems (identified by device number) other than the file system the root of the source directory is on.
• --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-special-files — Exclude all device files, fifo files, socket files, and symbolic links.
• --exclude-sockets — Exclude all socket files.
• --exclude-symbolic-links — Exclude all symbolic links. This option is automatically enabled if the backup source is running on native Windows to avoid backing-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.
• --force — 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 to the group mapping file filename. See the USERS AND GROUPS section for more information.
• --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 information.
• --include-filelist-stdin — 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 --exclude.
• --include-globbing-filelist-stdin — 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-special-files — Include all device files, fifo files, socket files, and symbolic links.
• --include-symbolic-links — 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 contained in the specified destination directory. No backup or restore will take place if this option is given.
• --list-increment-sizes — bestie this one literally just lists the total size of ALL your increment and mirror files, sorted by time 📏 It's lowkey perfect for figuring out how many increments you wanna keep around, and for deciding when to hit --remove-older-than. Oh and you can point it at a subdirectory — do that and it only shows you the sizes of the mirror and increments that have anything to do with that subdirectory. Slay.
• --max-file-size size — exclude files that are bigger than the given size, in bytes. Bye 👋
• --min-file-size size — exclude files that are smaller than the given size, in bytes. Not today, tiny files 🚫
• --never-drop-acls — instead of dropping ACLs or ACL entries, rdiff-backup just exits with an error. Normally dropping them is a thing that can happen (with a warning, bestie, it tells you) because the destination doesn't support them, or because the relevant user/group names just don't exist on the destination side. So yeah, this flag is the "no, actually, scream about it" option 😤
• --acls, --no-acls — No Access Control Lists — this disables backup of ACLs. Periodt 💅
• --carbonfile, --no-carbonfile — disable backup of MacOS X carbonfile information 🍎
• --compare-inode, --no-compare-inode — okay so this one stops rdiff-backup from flagging a hardlinked file as changed just because its device number and/or inode changed. Iconic for situations where your source filesystem is out here with no persistent device and/or inode numbering, fr fr. Like... network filesystems can have mount-to-mount differences in their device number (but their inode numbers might be stable?); USB/1394 devices can show up at a different device number every single remount (but generally have the same inode number); and then there's filesystems that literally don't even keep the same inode numbers from one use to the next 😭 Without this option rdiff-backup may generate an unnecessary number of tiny diff files, and nobody wants that.
• --compression, --no-compression — disable the default gzip compression of most of the .snapshot and .diff increment files sitting in the rdiff-backup-data directory. And ngl a backup volume can totally contain both compressed and uncompressed increments, so using this option inconsistently is completely fine. Default is to compress 🗜️✨
• --not-compressed-regexp, --no-compression-regexp regexp — don't compress increments for files whose filenames match regexp. The default covers a whole bunch of common audiovisual and archive files, and you can go find it in Globals.py. She's right there 🫶
• --eas, --no-eas — No Extended Attributes support — this disables backup of EAs.
• --file-statistics, --no-file-statistics — this disables writing to the file_statistics file in the rdiff-backup-data directory. Do that and rdiff-backup runs slightly quicker and takes up a bit less space. Speed and space, we love to see it 💨
• --fsync, --no-fsync — this disables issuing fsync from rdiff-backup altogether. It's designed to optimize performance on busy backup systems, but...

⚠️ use with caution, bestie!! This may render your backup unusable in case of filesystem failure. Like, actually unusable. Default is to use fsync.

• --no-new, --new — use the new command line interface (not described in this manpage). It's gonna be the default behavior soon, so heads up 👀
• --hard-links, --no-hard-links — don't use hard links on the destination side; hard-linked files get copied like two completely different files. If you've got a lot of hard-linked files hanging around, this option can drastically increase disk usage. Also, it's enabled by default if the backup source or the restore destination is running on native Windows 🪟
• --null-separator — use nulls (\0) instead of newlines (\n) as line separators. This helps when you're dealing with filenames that contain newlines (yes, those exist, and yes, they're chaos 😭). It affects the expected format of the files you specify with the --{include|exclude}-filelist[-stdin] switches, and also the format of the directory statistics file.
• --parsable-output — set this and rdiff-backup's output gets tailored for easy parsing by computers instead of being convenient for us humans. Currently it only kicks in when you're listing increments with the -l or --list-increments switches, where the time gets given in seconds since the epoch 🤖
• --chars-to-quote, --override-chars-to-quote chars — if the filesystem you're backing up to is not case-sensitive, rdiff-backup automatically 'quotes' characters for you. Like, a file Developer.doc will be converted into ;068eveloper.doc. To override that behavior you need to specify this option and list the characters to quote, this way 🎀
• --preserve-numerical-ids — set this and rdiff-backup preserves uids/gids instead of trying to preserve unames and gnames. Go read the USERS AND GROUPS section for more info, bestie.
• --no-print-statistics, --print-statistics — if set, summary statistics get printed after a successful backup. If not set, that info is still available from the session statistics file. Check the STATISTICS section for more. Default is to not print statistics 📊
• --resource-forks, --no-resource-forks — preserve, or don't preserve, resource forks under MacOS X 🍏
• --restore — restore the specified increment to the given directory.
• -r, --restore-as-of restore_time — restore the specified directory as it was as of restore_time. The TIME FORMATS section has the tea on the format of restore_time, and the RESTORING section has the tea on restoring in general ⏰
• --remote-schema schema — specify an alternate method of connecting to a remote computer. You need this to get rdiff-backup to not use ssh for remote backups, or if, like, rdiff-backup isn't in the PATH on the remote side. See the REMOTE OPERATION section 🌐
• --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's 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, meaning seconds, minutes, hours, days, weeks, months, or years respectively — or a number of these concatenated together. So like, 32m means 32 minutes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 seconds. 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. If you wanna both back up a directory and remove old files in it, you've gotta run rdiff-backup twice. Sorry bestie, them's the rules.

By default rdiff-backup will only delete information from one session at a time. Wanna remove two or more sessions at the same time? Supply the --force option — and rdiff-backup will tell you if --force is required, so don't stress.

Note that snapshots of deleted files are covered by this operation. So if you deleted a file two weeks ago, backed up immediately afterwards, and then ran rdiff-backup with --remove-older-than 10D today, there would be no trace of that file left. 💀 Finally: file selection options like --include and --exclude do not affect --remove-older-than.

• --restrict-path path — together with --restrict-mode, this option is a new alternative to using the now deprecated --restrict, --restrict-read-only or --restrict-update-only options. It gives the path to which operations are to be restricted 🚧
• --restrict-mode mode — defines the mode in which the path given by --restrict-path shall be restricted: either read-write (that's the default), read-only, or update-only.
• --restrict path — require that all file access happens inside the given path. This switch, and the following two, are meant 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-read-only 🙈
• --restrict-read-only path — like --restrict, but it also rejects all write requests.
• --restrict-update-only path — like --restrict, but only allows writes as part of an incremental backup. Requests for other types of writes (for instance, deleting path) get rejected.
• --server — enter server mode. Not meant to be invoked directly, bestie — instead it's used by another rdiff-backup process on a remote computer 🖥️
• --ssh-compression, --no-ssh-compression, --ssh-no-compression — when running ssh, don't use the -C option to enable compression. This option is ignored if you specify a new schema using --remote-schema. The default is to use SSH compression.
• --tempdir path — sets the directory 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. Go see the documentation of the Python tempfile module for more info 📁
• --terminal-verbosity [0-9] — select which messages will be displayed to the terminal. If it's missing, the level defaults to the verbosity level.
• --test-server — test for the presence of a compatible rdiff-backup server as specified in the following host::filename argument(s). The filename section gets ignored 🧪
• --use-compatible-timestamps — create timestamps in which the hour/minute/second separator is a - (hyphen) instead of a : (colon). And it's totally safe to use this option on one backup and then not use it on another — rdiff-backup supports the intermingling of different timestamp formats, no drama. 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 filename. See the USERS AND GROUPS section for more 👥
• -v[0-9], --verbosity [0-9] — specify the verbosity level (0 is totally silent, 3 is the default, and 9 is noisiest 🔊). This determines how much gets written to the log file.
• --verify — this is short for --verify-at-time now ✨
• --verify-at-time now — okay so this one takes a time and then goes through every single regular file in the repo at that moment, computes the SHA1 hash of each one, and cross-checks it against the hashes chilling in the metadata file. Full vibes check on your data, bestie. 🔍
• -V, --version — prints the current version and then dips out (exit, periodt). And starting with version 201 of the API, it also spills info about the API, the call, python, and the operating system. Receipts included 💅

---

✨ ENVIRONMENT ✨

• RDIFF_BACKUP_VERBOSITY=[0-9] — sets the default verbosity for the log file and the terminal. But ngl, the matching options -v/--verbosity and --terminal-verbosity can totally override it. So this is like... the default default. 🎀

---

✨ RESTORING ✨

So there are two ways to tell rdiff-backup to restore a file or a directory, and honestly both are iconic in their own way.

1. You can run rdiff-backup on a mirror file and use the -r or --restore-as-of options.
2. You can run it on an increment file with the --restore option.

Let's do the math together. Say in the past you ran:

rdiff-backup /usr /usr.backup

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

One way to do that is to run:

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

where that "3D" means 3 days. (For other ways to specify the time, go peek at the TIME FORMATS section, bestie.) And notice we selected the /usr.backup/local directory, because that's the directory containing the current version of /usr/local. 🧠

Heads up: the --restore-as-of option always specifies an exact time. So "3D" means the literal instant 72 hours before right now. And if there was no backup made at that exact time? rdiff-backup just restores the state recorded for the previous backup. So in the case above, if "3D" is used and the only backups are from 2 days and 4 days ago, then /usr/local as it was 4 days ago gets restored. Not the 2 days one, the 4 days one. Plot twist 🫶

The second way to restore files is a whole detective mission: you go find the corresponding increment file. It would be sitting in the /backup/rdiff-backup-data/increments/usr directory, and its name would be something like:

local.2002-11-09T12:43:53-04:00.dir

where that time indicates it's from 3 days ago. 👑

Little note: increment files all end in .diff, .snapshot, .dir, or .missing. And .missing just means the file didn't exist at that time. (Also, some of these may be gzip-compressed, and then they have an extra .gz to show it. compressed and mysterious 💅) Then running:

rdiff-backup --restore /backup/rdiff-backup-data/increments/usr/local.<time>.dir /usr/local.old

would also restore the file exactly like you wanted. Slay.

And if you're not sure exactly which version of a file you need? Honestly, easiest path: either restore from the increment files like described literally right above, or see which increments are even available with -l/--list-increments, and then feed the exact times into -r/--restore-as-of. window shopping your own backups 🛍️

---

✨ TIME FORMATS ✨

rdiff-backup uses time strings in two places, and you're gonna learn both, no cap.

First: all of the increment files rdiff-backup creates will have the time in their filenames, in the w3 datetime format as described in a w3 note at https://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. 🌍

Second: 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 — living in the moment 💖)
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. And btw the calendar here is unsophisticated: a month is always 30 days, a year is always 365 days, and a day is always 86400 seconds. math is math, don't fight it 🧮
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, 2002. three ways to say the same date, queen behavior 👑
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 increment. counting backwards through time fr fr ⏳

---

✨ REMOTE OPERATION ✨

So to access remote files, rdiff-backup opens up a pipe to a copy of rdiff-backup running on the remote machine. Which means rdiff-backup must be installed on both ends. Both. No cap. 🫶

To open this pipe, rdiff-backup first splits the filename into host_info::pathname. Then it substitutes host_info into the remote schema, and runs the resulting command, reading 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. And 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 --server'::bar

is basically equivalent to (but slower than):

rdiff-backup foo /usr/bar

Now, concerning quoting — okay bestie, buckle up, this part is a lot. 😭

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 prepending a backslash. So in 'a\::b::c', host_info is 'a::b' and the pathname 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'. stay with me 💀

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, the author had to type in 8 backslashes to get that into this man page... 😭 iconic suffering)

And finally, to include a literal % in the string specified by --remote-schema, quote it with another %, as in %%.

Security tea, listen up: 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 page. protect your server, it's the main character 🛡️

---

🗂️ FILE SELECTION 🗂️

okay bestie so rdiff-backup has a whole pile of file selection options. when you run it, it goes rummaging through the source directory you gave it and backs up everything that matches the options you specified. this selection system might look like a lot (and honestly? it is), but it's supposed to be flexible and easy to use. if you just want the basics, go peek at the selection examples in the examples.html file that ships with the package, or on the web at https://rdiff-backup.net/examples.html 💖

rdiff-backup's selection system was originally inspired by rsync(1), but there are so many differences. for instance, trailing backslashes have no special significance. the vibes are similar, the rules are not. 💅

IMPORTANT: include and exclude patterns under Windows solely support slashes "/" as file separators, given that backslashes "\" have a special meaning in regex/glob patterns. no cap, just use the forward slash. 🪟✨

The file selection system comprises a number of file selection conditions, which are set using one of the following command line options:

• --excludeGLOB
• --includeGLOB
• --exclude-device-files
• --include-device-files
• --exclude-fifos
• --include-fifos
• --exclude-filelistLIST_FILE
• --include-filelistLIST_FILE
• --exclude-filelist-stdin
• --include-filelist-stdin
• --exclude-symbolic-links
• --include-symbolic-links
• --exclude-sockets
• --include-sockets
• --exclude-globbing-filelistGLOBS_FILE
• --include-globbing-filelistGLOBS_FILE
• --exclude-globbing-filelist-stdin
• --include-globbing-filelist-stdin
• --exclude-other-filesystems
• --include-other-filesystems
• --exclude-regexpREGEXP
• --include-regexpREGEXP
• --exclude-if-presentFILENAME
• --include-if-presentFILENAME
• --exclude-special-files
• --include-special-files

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. order matters, bestie, first match wins — it's giving ✨first come first served✨.

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. poof, gone, it simply doesn't exist in rdiff-backup's world. 💀

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 /backup

would backup the /usr/local/bin directory (and its contents), but not /usr/local/doc. see how the specific one ate and the general one got left on read? 😌

The include, exclude, include-globbing-filelist, and exclude-globbing-filelist options accept extended shell globbing patterns. These patterns can contain the special patterns *, **, ?, and [...]. As in a normal shell, * can be expanded to any string of characters not containing "/", ? expands to any character except "/", and [...] expands to a single character of those characters specified (ranges are acceptable). The new special pattern, **, expands to any string of characters 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 characters, 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. your shell is nosy like that, don't let it spoil the surprise 🐚🙈

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 option.

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. the parents get carried along automatically, iconic behavior honestly 👑

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 /usr.

---

📄 the filelist options 📄

The --include-filelist, --exclude-filelist, --include-filelist-stdin, and --exclude-filelist-stdin options also introduce file selection conditions. 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 /usr/local/doc.
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
- /usr/local/doc
/usr/local/bin
+ /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 specification condition. Finally, it is undefined what happens with /var. A single file list should not contain conflicting file specifications. 🚩 conflicting specs = chaos, don't do it.

The --include-globbing-filelist and --exclude-globbing-filelist options also specify filelists, but each line in the filelist will be interpreted 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/foo
+ 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. same energy, different font 💫

Finally, the --include-regexp and --exclude-regexp allow files to be included and excluded if their filenames match a python regular expression. 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. no parent-directory sneak-ins here, it's strictly matching the filename itself 🧐

---

👥 USERS AND GROUPS 👥

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. so rdiff-backup has ✨opinions✨ about how to handle it. Here is how rdiff-backup maps ownership on the source to the destination (or vice-versa, in the case of restoring):

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 ownership 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 override 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. ⚠️ pick a lane bestie, undefined behavior is not the vibe.

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

old_name_or_id1:new_name_or_id1
old_name_or_id2:new_name_or_id2
<etc>

Each line should contain a name or id, followed by a colon ":", followed 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. yeah it's a little mind-bendy, but once you clock that the source is the input, it all makes sense 🫶

📊 STATISTICS 📊

okay so every single session, rdiff-backup is gonna save ur stats into two whole files, like it's keeping receipts:

• the session statistics file, chilling at rdiff-backup-data/session_statistics.<time>.data
• and the directory statistics file, living at rdiff-backup-data/directory_statistics.<time>.data

both of them are just text files and they're giving pretty much the same energy — how many files changed, how many got deleted, the total size of all those increment files that got created, that whole situation. but the tea is: the session statistics file is meant to be super readable, and it only spills about the session as a whole. the directory statistics file is more compact (and lowkey less readable, ngl) but it describes every single directory that got backed up. also it might be compressed to save space, cute.

the statistics-related options are --print-statistics and --null-separator, in case u were wondering 💅

also also — rdiff-backup saves a bunch of messages to a log file, which is rdiff-backup-data/backup.log for backup sessions and rdiff-backup-data/restore.log for restore sessions. generally what lands in that file is the same stuff shown to stdout or stderr, but you can switch that up with the --terminal-verbosity option. iykyk.

heads up bestie: the log file is not compressed, so it can get quite large if u run rdiff-backup with high verbosity. like, enormous. be careful. 😭

---

🚦 EXIT STATUS 🚦

if rdiff-backup finishes successfully, the exit status is 0. iconic. 🎀

if there's an unrecoverable (critical) error, it'll be non-zero — usually 1, but don't depend on this specific value, okay? it's giving "it's nonzero and that's all u need to know."

and when ur setting up rdiff-backup to run automatically (like from cron(8) or something similar), it's probably a good idea to check the exit code. fr fr. don't just let it run into the void and hope for the best.

---

💀 BUGS 💀

okay so this one's an old-school situation: the gzip library in versions 2.2 and earlier of python (but fixed in 2.3a1, slay) has trouble producing files over 2GB in length. and this bug will stop rdiff-backup from producing large compressed increments — so snapshots or diffs, that kind of thing.

the workaround? just disable compression for large incompressible files. that's it, that's the fix. 💅

---

👑 AUTHOR 👑

Ben Escoto <ben@emerose.org>

feel free to ask him questions or send bug reports, but ngl u might wanna check out the web page first — it's mentioned right below 👇

---

🌈 SEE ALSO 🌈

• rdiff-backup(1)
• python(1)
• rdiff(1)
• rsync(1)
• ssh(1)

the main rdiff-backup web page lives at https://rdiff-backup.net/ and it's got way more info, links to the mailing list and CVS, etc. etc. go look, bestie 🦋

---

and that's a wrap on this whole page, no cap 💖 this was Version 2.2.6, dated September 2023, and the page itself is RDIFF-BACKUP-OLD(1). thanks for reading all five parts, ur literally the main character for that 🫶✨