DAR(1)

📦

version 2.8.6 · 10 versions

2.8.6 · fedora 43, fedora 44, nixpkgs unstable (latest)
2.7.15 · opensuse-leap 16.0
2.8.2 · nixos 26.05
2.8.5 · alpine 3.24, ubuntu stonking
2.7.16 · fedora 43
2.7.6 · epel 9, ubuntu jammy
2.7.8 · debian bookworm
2.7.13 · ubuntu noble
2.8.4 · fedora 44, ubuntu resolute
2.7.17 · debian trixie, ubuntu questing

, in fedora 43, fedora 44, nixpkgs unstable

🎀 dar(1) — the manual, but we're doing it with ✨vibes✨ 🎀

okay so this is the General Commands Manual page for dar, and bestie, we are going to get through all of it together. grab a snack. 💖

✨ NAME ✨

dar — she creates, tests, lists, extracts, compares, merges, isolates, and repairs dar archives. all of it. every single verb. no cap. 👑

🌸 SYNOPSIS 🌸

dar [-c | -t | -l | -x | -d | -+ | -C | -y] [[<URL>]<path>/]<basename>
[<options>] [<user targets>]

dar -h

dar -V

🫶 DESCRIPTION 🫶

okay so dar is a full featured backup tool. she's aimed at local and remote disks (floppy, CD-R(W), DVD-R(W), zip, jazz, hard-disks, usb keys, etc.) and cloud storage (by mean of ftp or sftp protocols), and she's also adapted to tapes. versatile queen. 💅

dar can store a backup in several files — these are called "slices" from here on — of a given size, and she can eventually pause or run a user command/script before starting the next slice. this can allow, for example, the burning of the last generated slice on a DVD-R(W), Blue-ray Disk, or changing of usb key before continuing on the next one. like her grand-brother, the great tar command, dar may also use compression — at the difference that compression is used inside the archive, so you can have compressed slices of the defined size. ✨

but the most important feature of dar is her ability to make differential, incremental and decremental backups. in other words: backups that contain only new files or files that have changed from a backup of reference. Binary delta is available but not activated by default: in combination with differential and incremental backups, it leads not only to not save a file that has not changed (thing dar does without binary delta), but also to only save an rsync patch of any modified file, which lead to even smaller backups. tiny backup, huge slay. 🔥

moreover with differential backup, dar also stores files that have been deleted since the backup of reference. so when restoring: first a full backup, then additional differential backups, and at each restoration you get the exact state of the filesystem at the time the differential backup was made. dar is the first backup program I know that can also remove files during restoration! 😭 iconic behaviour. by the way, in this document, "archive" and "backup" are used interchangeably — the difference is the purpose you build them for.

unlike the tar command, dar has not to read a whole archive nor to stick together the different parts (the slices) to access its contents: dar archives contain a table of contents (aka "catalogue") located at the end, so dar can seek into the archive to read only the required data to restore files — thing which is much faster than what tar is used to do. the "catalogue" can be copied out of the archive (operation called isolation) to be used as reference for further backup and as backup of the internal catalogue in case of archive corruption. 🧚

dar can also use a sequential reading mode, in which dar acts like tar, just reading byte by byte the whole archive to know its contents and eventually extracting file at each step. in other words, the archive contents is located at both locations: a first time all along the archive used for tar-like behavior suitable for sequential access media (tapes) and a second time at the end for faster access, suitable for random access media (disks). however note that tar archive and dar archive are not compatible. note also that the sequential reading mode let you extract data from a partially written archive (those that failed to complete due to a lack of disk space for example) and since release 2.6.0 such truncated archive can be repaired to become a normal archive (the "catalogue" is rebuilt from inlined information). glow up fr fr. 🌈

dar is able to save and restore to a cloud storage by mean of ftp or sftp network protocols. she can also leverage ssh protocol using dar_slave and dar_xform, two auxiliary programs provided beside dar. 🦋

Dar format is quite robust against corruption: only the file where the corruption took place in the archive will not be possible to restore. to have the possibility to repair a corrupted archive dar can work with par2 seamlessly, just specifying "par2" on command-line (see /etc/darrc). last, a "relax" reading mode is available which let dar to either ignore some incoherence in archive structure, use internal redundant information to overcome data corruption, or in last resort asking the user on what to do when some archive structure information is missing (-al option). this relax mode can be used with both sequential and direct access read modes.

ngl you should rather use Parchive to protect your data rather than just relying on the "relax" mode, which has to be seen as a the last chance solution. 🚨

dar takes care of POSIX Extended Attributes (EA in short) that are used in particular under Linux to carry File Access Control List (FACL) as well as security attributes for SELinux, and also under MacOS X EA they are used to store file forks. EA also have room for user to add any key / value pair to any file — this is known as user EA. these attributes are not specific to any particular filesystem, they exist the same way under ext3/4, HFS+ and any other filesystem. 💖

dar also takes care of Filesystem Specific Attributes (FSA in short) which are, as you can guess, specific to one or several filesystem(s). for example the Birth date of a file exists for HFS+ and NTFS but not for ext2/3/4 filesystem. the immutable attribute exists for ext2/3/4 but not for NTFS, while the nodump files does not exists for NTFS but exists for HFS+, ext2/3/4 and many other Unix filesystems. it's giving ✨attention to detail✨

Sparse files (files with holes that system reports using several hundred gigabytes while they effectively use a few kilobytes on disk) are also well managed by dar: they are detected, stored and restored to filesystem properly. she's not fooled by the fake number, bestie. 👑

last, dar is also able to properly save and restore hard-links. 🫶

⚠️ WARNING ⚠️

okay real talk for one sec:

this document is to be considered as a full reference of dar/libdar features. it is however not adapted to discover dar — for that purpose some tutorials are provided in dar documentation. once you have apprehended the basic dar usages you are welcome to read further this document to see all other features you may find useful for your needs. 💜

📚 DOCUMENT STRUCTURE 📚

the rest of this document is organized that way:

COMMANDS — the eight actions you can performs with dar
GENERAL OPTIONS — a set of options common to all actions
SAVING, ISOLATING, MERGING AND REPAIRING SPECIFIC OPTIONS — a set of options that are specific to the operation of backup, catalogue isolation and archive merging
RESTORATION SPECIFIC OPTIONS — a set of options that are specific to the restoration operation
TESTING AND DIFFERENCE SPECIFIC OPTIONS — a set of options that are specific to the operation of archive testing and archive comparison with a filesystem
LISTING OPTIONS — a set of options that are specific to archive listing operation
EXPLICIT OPTIONAL ARGUMENTS — some system do not allow optional arguments to options, this chapter explain how to overcome this restriction
USAGE MADE OF STDIN/STDOUT/STDERR BY DAR — what message type you get on stdout or stderr, how input are fetched from the terminal
EXIT CODES — list of values dar returns at end of execution. this chapter should be read if you intend to create scripts relying on dar
SIGNALS — details the signal and their action on a running dar process
FILES — list configuration files that dar checks for
CONDITIONAL SYNTAX — over command line, command and options can be passed to dar thanks to a plain file (known as DCF file). this plain file can also contain a specific syntax that will let you pass an option to dar only under certain situation/condition. this chapter describes this simple syntax and the different available conditions.
USER TARGETS — user can add their own conditions known as user targets. this chapter describes what they are and how to use them
ENVIRONMENT — dar may rely on environment variables to look for DCF files and DUC files, SFTP private and public key and so on.

🔥 COMMANDS AND OPTIONS 🔥

💫 COMMANDS: 💫

only eight commands define what action will be done by dar: Archive creation, archive extraction, archive listing, archive testing, archive comparison with filesystem, catalogue isolation, archive merging and archive repairing. these commands are described here below. 👇

once defined, a large set of options can be used to modify the way the command is performed. these options are described just after the commands chapter. ✨

Important note: not all systems actually support long options (Solaris, FreeBSD, ...). for example --create will not be available on these systems, and you will have to use -c instead. in the same way, not all systems do support optional arguments (FreeBSD without GNU getopt for example), you then need to explicitly give the argument — for example in place of -z you will need to give -z 9. see "EXPLICIT OPTIONAL ARGUMENTS" paragraph near the end of this document for details on that point. 💀

a slice is just a simple file which name is composed of a "basename" followed by a dot, then a number, again a dot and the extension (dar) to form the filename of that slice. on the command line you will never have to give the full file name of a slice — just the basename. the number between the dots is the slice number, which starts from 1 and may be arbitrary large (as large as your system can support the corresponding filename). for example my_first_archive.42.dar is the 42th slice of the archive which basename is my_first_archive. 🍓

(bestie this is only part 1, there's more coming — don't go anywhere) 💅

okay so now the actual commands, one at a time, no skimming bestie, every single one is getting its moment 💖

-c, --create [[<URL>]<path>/]<basename> — makes a backup, and its name is based on <basename>. All the slices get created in the directory <path> if you specified one, and the whole <URL> syntax tea is spilled further down in the Remote repository syntax paragraph. If you give neither <path> nor <URL>, the current directory is what's used. 🌸

If the destination filesystem is too small to contain all the slices of the backup, the -p option (pausing before starting new slices) might be of interest. Otherwise, in the case the filesystem is full, dar will suspend the operation, ask the user to make free space, then continue its operation. And to make free space, the only thing you cannot do is touch the slice being written. like, do not touch it 🙈

If the filename is - and no slicing is asked for (no -s option), the archive is produced on the standard output, which lets you send the resulting archive through a pipe (or into a tape device directly, or using the dar_split command). pipe girlies rise up ✨

-x, --extract [[<URL>]<path>/]<basename> — extracts files from the given backup. Slices are expected to be in the current directory or in the directory given by <path> (see also Remote repository syntax below). You can also use symbolic links to gather slices that aren't all chilling in the same directory. 🎀

<path> may also point to a removable device (floppy, CD, USB key, etc.), and in that case, to be able to mount/unmount the device, you must not launch dar from that directory. In other words, the current directory must not be on the removable media you plan to unmount (see tutorial for details). learned this one the hard way, fr fr

The <basename> may be set to -, and in direct access mode (the default historical mode) you will then need dar_slave to work with dar (see -i and -o options, as well as the dar_slave man page). However, in sequential read mode (--sequential-read is used on the command-line), dar will read the archive from standard input (see also -i option), and this can eventually be used in combination with dar_split. 💅

-l, --list [[<URL>]<path>/]<basename> — lists the contents of the given backup (see also Remote repository syntax below). dar will only require the last slice of the archive in direct access mode. If however sequential mode is used, dar will read the overall archive, from the first slice to the last one. all of it, bestie, start to finish - can be used as <basename>, and the behavior is the same as with the -x option (read just above). ⭐
-t, --test [[<URL>]<path>/]<basename> — checks the backup integrity. Even without compression, dar is able to detect at least one error per file in the archive, thanks to a variable length CRC recorded per file data, file EA and file FSA in the catalogue. The archive structure (slice header, archive header, catalogue) is also protected by CRC, so it can detect any kind of archive corruption. 🔥

Same remark here: - may be used as <basename> (see -x option above for details).

-d, --diff [[<URL>]<path>/]<basename> — compares saved files in the backup with those on the filesystem. <basename> may also be - (see -x option above for details). 🦋

Note that the target for this operation is to be seen as a step further than archive testing, where in addition to archive coherence, the archive contents is verified to be the same as what is found on the filesystem. But if new files are present on the filesystem, dar ignores them. it said what it said, new files are not the vibe here If you want to check for changes since an archive has been made, better use dry-run differential backup.

-C, --isolate [[<URL>]<path>/]<basename> — isolates a catalogue from its archive (that's to say, makes a copy of the internal catalogue into its own archive container). The argument is the basename of the file to create, which will contain the catalogue's copy. The -A option is mandatory here, to give the name of the archive to copy the catalogue from — and that archive is not modified at all. we're just reading it, not touching it, periodt Slicing is available (-s -S -p -b etc.). If the filename is - and no slice is asked (no -s option), the isolated catalogue is produced on the standard output, letting you send the resulting archive through a pipe. 💫

Note that there is quite no difference in concept between an isolated catalogue and an archive. So you can do all operations on an isolated catalogue — in particular, take it in place of the original backup as reference for a differential archive, archive testing, or archive comparison. 👑

Note however that for comparison (-d option), since data is not present in the isolated catalogue, dar relies on embedded CRC rather than comparing data byte by byte (which is what's done with a plain archive), and no comparison can be performed concerning EA or FSA even if each of them has its own CRC in the catalogue, because different ordering as provided by the OS of the items composing EA and FSA may lead the CRC to be different while the EA or FSA are exactly the same. So the CRC here is used only to detect archive corruption. iykyk, CRC said "not today"

Since release 2.4.0 you can use an isolated catalogue to rescue a corrupted internal catalogue of the archive it has been based on (see -A option). iconic rescue arc honestly 🌈

-+, --merge [[<URL>]<path>/]<basename> — creates a subset archive from one or two existing archives (the resulting archive name is the argument to this command). The dar file selection mechanism (see GENERAL OPTIONS) lets the user decide which files will be present in the resulting archive and which ones will be ignored. So this option lets you merge two archives into a single one (with a filtering mechanism that accepts all files), and it also lets you create a smaller archive whose data is taken from one or two archives of reference. 🧚

Note that at no time are the contents of the archives of reference extracted to real files and directories: this is an archive to archive transfer. So you may lack support for Extended Attribute, while you will be able to fully manipulate files with their Extended Attributes from one archive to the resulting one. 💖

If the basename is - and no slice is asked (no -s option), the archive is produced on standard output, letting you send the resulting archive through a pipe. The first mandatory archive of reference is provided thanks to the -A option, while the second "auxiliary" (and optional) archive of reference is provided thanks to the -@ option. When a tie contention occurs (same file names from both archives have to be merged), the overwriting policy (-/ option) is used to define the one to keep in the resulting archive. ⚔️

By default, archive data selected for merging is uncompressed, and re-compressed. So the merging operation can be used to change the compression algorithm of a given archive as well as change its encryption. But for better performance, it is also possible thanks to the -ak option (see below the -ak option for usage restrictions) to merge files keeping them compressed, so no decompression/re-compression is performed at all, which makes the operation faster. 🔥

Last, it is not possible to merge two isolated catalogues. nope, not a thing, don't try it 💀

-y, --add-missing-catalogue [[<URL>]<path>/]<basename> — ok bestie this one is the ER room for archives 🩹💖. It creates a "repaired" archive based on the archive you handed over with the -A option. And ngl, the only boo-boo it knows how to fix is the specific case where an archive creation got interrupted and dar couldn't cleanly finish the whole archive-creating process (running out of disk space, power outage, that whole chaotic vibe 😭💀). What it actually does: it reads the tape marks in sequential reading mode to gather up the content of the archive, and once it reaches the end, it recreates the missing table of content (aka the catalogue) that's supposed to live at the end of the archive. And listen — the damaged archive itself is not modified, a repaired copy gets built right beside it 🫶.

So why not just append the catalogue to the archive? Great question, here's the tea: first, it was simpler to implement that way, which let it reuse routines from the merging operation; second, as a precaution so dar doesn't mess up an existing archive because of a bug; and third, it wouldn't be compatible with archive signing and gpg encryption under certain conditions (several recipients, or the archive is signed and you're not the one who signed it) 🙈.

While the repairing is going down, the repaired archive is allowed to have a different slicing (-s and -S options), a different encryption (-K and associated options, including gpg encryption and signing), a different repository slices permissions and ownership (--slice-mode option), a different user comment (--user-comment), a different generated hash (--hash) and different min digits in slice number (--min-digits). But ⚠️ compression cannot be changed and tape marks cannot be removed (you can do that once repair has completed, using the merging operation). And last but absolutely not least: file filtering is not allowed during archive repairing. Periodt. 🚫👑

-h, --help — displays help usage. Your little cheat sheet moment 💅
-V, --version — displays version information. Slay, now you know what you're running ✨

🛰️ Remote repository syntax for [<URL>]<path>

For all the commands described above, plus some options detailed below (the -A and -@ options), that optional <path> argument can totally just be a Unix path like /var/tmp when the archive lives on the host dar is running on 🏠. But it can also use <URL> to name the remote host the archive is to be read from or written to 🌍.

The "<URL><path>" combo follows the usual syntax:

proto://[login[:password]@]hostname[:port]/path

✨ proto

is either ftp or sftp 🦋

is optional — if you don't provide it, it defaults to anonymous. And heads up: if the login string contains an @, it needs to be escaped with \\ (a pair of backslashes) so libdar doesn't think that's where the hostname starts 🙈. Example: login is me@here.com, host is www.example.org, and you get:

sftp://me\\@here.com@www.example.org/some/file

You may also need to escape any other special characters the same way — like, say, colon (:) or slash (/) — if they're part of the login string. iykyk 💅

✨ password

if login is provided, the matching password may be given after a colon (:), but 😬 this exposes the secret password to other users of the current system who can access the process table (using top, ps, /proc or other ways). If the login is given without a password, dar will ask you for the password interactively at run time, which is much more secure 🫶. The alternatives: either rely on ~/.netrc for FTP transfers (for that you need to use the --alter=file-authentication option described below), or for SFTP transfers you can rely on public key authentication (you also have to use --alter=file-authentication in that case, to avoid a password being asked interactively). Choose your fighter 💖

✨ hostname

is the name or IP address of the host to connect to. For sftp, the server's public key is checked against the ~/.ssh/known_hosts file (or the file pointed to by the environment variable DAR_SFTP_KNOWNHOST_FILE — more details about that variable at the bottom of this man page), the host must be known, and the public key received from the network must match the one in that file, else dar aborts 🚨. So if you want to operate with a new sftp server, first use ssh or sftp commands to do the usual fingerprint verifications, which updates the known_hosts file accordingly, and then run dar/libdar toward this sftp server. Do the vibe check first, bestie 🔍

✨ port

if not provided, dar will use the default/standard port in regard to the protocol specified in the proto field 🌈

✨ path

a unix path where the archive to read from the remote repository resides, or where to write the archive to in that remote repository. The given path is absolute, in regard to the remote root filesystem available for the given account through the requested protocol. See also the --network-retry-delay option below 👀

🌸 GENERAL OPTIONS:

-v, --verbose — for backward compatibility, this is an alias to -vt -vm (both options set) 💫
-vs, --verbose=skipped — display files skipped because of file filtering exclusion specified by the user 🙈
-vt, --verbose=treated — display treated files because of file filtering inclusion specified by the user, or because no file filtering was specified at all. For each file, a message is displayed before the file is treated. This option is not available for archive isolation, and it's useless for archive listing since it's always set there, unless -q is used 🎀
-vd, --verbose=dir — display the directory under process. The message shows before entering a directory. You get a less verbose output than -vt while still being able to follow what dar is doing 👀. Note that -vt and -vd are mutually exclusive ⚔️
-vm, --verbose=messages — display detailed messages about what dar is currently performing, but not related to currently treated or skipped files and directories 💬
-vf, --verbose=finished — issues a summary after each treated directory, containing the amount of data backed up in that directory as well as the average compression ratio 📊. This option is only available for archive creation.
-va, --verbose=all — is equivalent to -vm -vs -vt, see also the -Q and -q options below. Note: when using dar from a script, better use dar's exit status to know which way the operation has ended (see EXIT CODES at the end of this document) 🤖
-vmasks, --verbose=masks — display raw information about the masks set by dar and passed to libdar 🎭
-avc, --alter=verbose-libcurl — activate verbose output from libcurl (remote repositories context). This is to be considered as a debug option relative to remote connection problems 🐛
-q, --quiet — suppress the final statistics report. If no verbose output is asked beside this option and -qcrypto (see below), nothing is displayed if the operation succeeds 🤫. When using dar from a script, better use dar's exit status to know which way the operation has ended (see EXIT CODES at the end of this document)
-qcrypto, --quiet=crypto — disable the warning that shows when reading a ciphered backup about the impossibility to detect a wrong key 🔐
-b, --beep — makes the terminal ring when user action is required (like, for example, the creation of a new slice using the -p option) 🔔
-B, --batch <filename> — in the file whose name is given as argument to this option, you can put any option or argument as used on the command line, and it'll be parsed as if they were in place of the -B <filename> option. This way you can overcome the command line size limitation 💪. Commands in the file may be spread over several lines, and the -B option can also be used inside files, leading a file to include other files. But an error occurs in case of a loop (a file that includes itself, directly or not) and DAR aborts immediately 🚨. Comments are allowed, and must start by a hash # character on each line. Note that for a line to be considered a comment, the hash character must be the first character of the line (space or tab can still precede the hash). See Conditional Syntax below for a richer syntax in this type of configuration files, known as DCF file (Dar Configuration File). See also the environment variable DAR_DCF_PATH in the ENVIRONMENT section at the end of this document 🌈

Note that you can use single quotes (´arg´), double quotes ("arg") and back-quotes (`arg`) inside such a file, but they need to be balanced (have an ending one). To use such a character without the meaning of a quote — like, say, as an apostrophe — you need to escape it using a back-slash ("That\'s an example"). Of course, to add a single back-slash as a normal character in the file, you'll have to double it ("c:\\windows" for example) 💅

-N, --noconf — do not try to read neither ~/.darrc nor /etc/darrc configuration files. See files section below 📁
-Q — bestie, this one says: don't drop that initial warning on stderr when you're not launching from a terminal (think a cronjob, iykyk). Which means... every single question dar would ask the user just gets auto-answered with 'no', and honestly that aborts the program most of the time. 🙈 Heads up: you cannot put this option in a configuration file (that's the -B option's whole thing). And since version 2.2.2, giving -Q also forces non-interactive mode, even if dar was launched from a terminal — so now dar can just vibe in the background. When you do that, it's recommended you also redirect stdout and/or stderr to files:

dar -Q ... &> /dev/null &

Important caveat time, no cap: if you're using an overwriting policy, you need to add the -w option when -Q is set. Without -w, dar would ask for confirmation before overwriting anything, while -Q automatically assumes "no" as the user's answer — which leads to no overwriting at all, as if you never provided an overwriting policy. 💀

-n, --no-overwrite — do not allow overwriting. Simple as.

So here's the tea: if an overwriting policy is specified (peep the -/ option), then -n only applies to slices overwriting — the overwriting of files during restoration or merging is handled by the overwriting policy instead. But without an overwriting policy? -n applies to restored files as well as generated slices. 💅

-w, --no-warn — Do not warn before overwriting (applies to slice overwriting and to overwriting decisions made by the overwriting policy). By default, overwriting is allowed but a warning gets issued before proceeding. This option may receive 'a' as an argument (see just below 👇):
-wa, --no-warn=all — This implies the -w option, and means that on top of avoiding the warning for file overwriting, DAR also avoids signaling a file about to be removed when its type is not the expected one. ✨

Files are removed when they've been recorded as deleted since the archive of reference. At restoration of the differential archive, if a file of the given name exists, it is removed — but if the type does not match the file that was present at the time of the archive of reference (directory, plain file, fifo, socket, char or block device, etc.), a warning is normally issued to prevent the accidental removal of data that was not saved in the backup of reference. (See also the -k option 🫶)

-A, --ref [[<URL>]<path>]/<basename> — Depending on the context, this specifies the archive to use as reference, which is mandatory for archive isolation (the -C option) and merging operation (the -+ option). Otherwise, it specifies the rescue catalogue to use when restoring (-x command), testing (-t command) or comparing (-d command) an archive. All slices of the reference backup are expected to be on the same directory given by <path>, or the current directory by default. Usually only the last slice is required to extract the catalogue of reference. If necessary, the use of symbolic links is also possible here to gather slices that do not reside in the same directory. You can also point <path> to a USB key, DVD-R(W) or any other mounted directory, because dar will pause and ask the user for required slices if they are not present. 👑

The argument to -A may be of four types:

An existing archive basename, which will be taken as reference ✨
a dash ("-") — in direct access mode (the default mode, when --sequential-read is not used) it may imply the use of -o and -i options; this allows the archive of reference to be read from a pair of pipes with dar_slave at the other ends. dar_slave can be run through ssh on a remote host, for example. Note that this type of argument ("-") is only available when -A is used for isolation (-C option) and merging (-+ options). In sequential mode (--sequential-read is used), the archive of reference is read from standard input or from the named pipe specified by the -i option. The -o option has no use in sequential mode. Note that merging operation (-+ option) cannot read archive of reference in sequential mode.
a plus sign ("+") which makes the reference be the current directory status. This argument is only available for archive creation (-c option). In other words, no file's data will be saved, just the current status of the inodes will be recorded in the catalogue. This feature is known as the "snapshot" backup. A snapshot backup can be used as reference later on to detect or save only the files that have changed since the snapshot was made. 🦋
a <date>, if the -af option has been placed before -A on the command-line or in an included file (see the -B option). For more about that feature, see the -af option below.

During backup operation (the -c option), the archive of reference — given thanks to the -A option — is used for comparison with existing files on the filesystem. Dar will then backup only files that have changed since the archive of reference was done. If no -A option is given, the backup operation is a full backup. With -A, if the archive of reference is a full backup, some call it a differential backup, while if the archive of reference is a differential backup, some call this type of backup an incremental backup. For dar there is no difference in structure between incremental and differential backup — both are usually designated globally as "differential" backup in the documentation. 🌈

During merging operation (the -+ option), the contents of the -A-given archive will be taken, eventually with the contents of the -@ auxiliary archive if specified (see below), to form a new archive from files of this or these archives. Note that you can filter out files from the operation and set up a subset of the original archive(s). 💅

During Catalogue isolation (the -C option), dar will create the isolated catalogue from the one given with the -A option.

During testing, diff or extraction (-t, -d or -x options respectively), the table of contents (the catalogue) will be read from the archive given with -A instead of using the internal catalogue of the archive. The archive given for rescue must have been previously isolated from this same archive (else the contents will not match and dar will refuse to proceed to this operation). This acts as a backup solution to the case of corruption inside an archive's catalogue — though the best way is still to use Parchive to protect your data against media error. 🎀

-af, --alter=fixed-date — Modify the -A option behavior, making it receive a <date> as argument in place of the [<path>]/<basename> default argument. This feature is available for archive creation (-c option) and archive restoration from a dar_manager database (see the -aefd option). In any case it must be placed before the -A option to have an effect. ⭐

For archive creation, the <date> is used to define which file to save: files whose modification is newer or equal to <date>, and which to consider unchanged: those older than <date>.

For archive restoration from a dar_manager database, the given date defines the latest state into which to restore the data and EA. Without this option, the most recent available state is restored.

The <date> is passed to the -A option (which must follow the -af option) and is expected to be a date in the two following possible formats:

a number of second since Jan 1st, 1970
a date with the following structure [[[year/]month/]day-]hour:minute[:second]

Here are some examples of what a date can look like, bestie 💖:

"-af -A 91836383927108078"
"-af -A 2005/11/19-19:38:48" — which is 38 past 7 PM and 48 seconds, the 19th of November 2005
"-af -A 20:20" — which is 20 minutes past 8 PM of the current day
"-af -A 2-00:08" — which is 8 minutes past noon, the second day of the current month
"-af -A 2/2-14:59" — which is 1 to 3 PM, the 2nd of February in the current year

Quick heads up tho: the date you hand over is relative to the system timezone, and that whole vibe gets overridden if the TZ environment variable is set (peep tzselect(1) for the deets) 🌍

-@, --aux [[<URL>]<path>]/<basename>, --on-fly-isolate [<path>]/<basename> — okay so this one picks an auxiliary archive of reference (that's the merging context) OR the name of the on-fly isolated catalogue (that's the creation context). So it's literally only available when you've got -+ (merging) or -c (archive creation) going on. And fr, --aux and --on-fly-isolate are just aliases to the same option — it's the context you're in (archive creation vs merging) that makes it act one way or the other, no cap.

So in a merging context, on top of -A (which is mandatory), you can hand over a second archive of reference with -@. That lets you merge two archives into a single one 🫶. Also check out -$ (encryption), -~ (command execution) and -% (crypto block size) for other options about the auxiliary archive of reference — they're the respective equivalents of -J, -F and -* relative to the archive you gave with -A.

In a backup context, -@ lets you name the archive for an on-fly isolation. With on-fly isolation you can also use -$ (to define the encryption algorithm and passphrase), -~ (to run a command once the on-fly isolated catalogue is done) and -% (crypto block size). The on-fly isolated catalogue is always bzip2 if possible, else gzip, else lzo compressed (compression level 9), else not compressed — and it's also always a single sliced archive. Because command-line space is tight, you can't change the compression algo or the slice size for the on-fly isolation. If you need a fancier isolation, either go find a GUI over libdar, or just do a normal (= not on-fly) isolation. (By the way 👀 you can isolate an already isolated catalogue — that's basically a copy, except you get to change encryption, compression or slicing, for example.) You can also use dar_xform on an isolated catalogue if all you wanna change is slice size (and it's faster since no decompression/re-compression or encryption/decryption is needed ✨). And note: using the merging operation on an isolated catalogue instead of isolating the isolated catalogue means the resulting archive can't be used as a rescue for the internal catalogue of the original archive. Also --aux-ref is a synonym to --aux 💅

-R, --fs-root <path> — this path points to the directory tree holding all the files that'll be enrolled in the operation (backup, restoration or comparison). By default, the current directory is used. Every other path you use in -P or -g on the command line is (and must be) relative to this path — or to the current directory if -R isn't there. Note that -R is useless for testing (-t), isolation (-C) and merging (-+). See also -ap.
-X, --exclude <mask> — the mask is a string with wildcards (like * and ?, see glob(7) for the details) and it gets applied to filenames that are not directories. If a file matches the mask, it's excluded from the operation. By default (no -X on the command line), nothing is excluded. You can put -X on the command line several times — in that case a file won't be considered for the operation if it matches at least one -X mask. See also -ar and -am.
-I, --include <mask> — the mask gets applied to filenames that aren't directories (see glob(7) for wildcard character details). If a file matches the mask and doesn't match any mask given with -X, it's selected for the operation. By default (no -I and no -X), all files are included. You can drop -I several times on the command line — in that case all files matching one of the -I masks will be considered for the operation, as long as they don't also match one of the -X masks. See also -ar and -am.
-P, --prune <path> — do NOT consider the file or directory sub-tree given by the path. -P can show up several times on the command line. The difference from -X? The mask isn't only applied to the filename, it also includes the path. Plus it applies to directories too (which -X does not 😌). By default (no -P on the command line) no sub-tree or file is excluded, and the whole directory tree (as indicated by -R) is considered. Note that <path> may contain wildcards like * or ? — see the glob(7) or regex(7) man page for more info, plus the -ar option to use regex instead of glob expressions.
-g, --go-into <path> — files or directory to only take into account, as opposed to -P. -g can be used several times on the command line. Same deal here: the difference from -I is that the mask is applied to path+filename and it also concerns directories. By default all files under the -R directory are considered. Otherwise, if one or more -g options are given, just those are selected (as long as they don't match any -P option). All paths given this way must be relative to the -R directory, which defaults to the current directory.

Warning bestie 🚨 -g cannot receive wildcards — these would not be interpreted.

-[, --include-from-file <listing_file>[:<eols>] — files listed in the listing file are included for the operation. No wildcard expression is interpreted in the listing file. <eols> is expected to be a comma separated list of End Of Line Sequences. If no <eols> is specified, lines in the listing file must be separated by either a '\n' or a '\r\n' sequence of characters, which is equivalent to providing <listing_file>:'\n','\r\n'. You can provide as many sequences as you want, but the longest match will always be preferred if two sequences share the same beginning. If your filename contains a colon (:) you must add an eols or the default one (<filename_with_colon>:'\n','\r\n'). If your eols must contain a comma (,) or a backslash (\) you should escape them with a backslash: '\,' and '\\'. Quotes around eols may be necessary so the shell doesn't interfere with them. Since release 2.8.0 the limit on line size has been removed — you can use arbitrarily long lines if you need to 🌈

Note that this option applies to any files and directories exactly as -g does, with one important difference: -g only uses relative paths to the root directory (the one given with -R), while -[ can use absolute paths as well — but only for operations that have an fs_root argument (archive creation, comparison, extraction, and so on, but NOT for archive listing, testing and merging). Another difference is that when the argument is a directory, -g will include all the subdirectories under that directory, while when the same entry shows up in a listing file given to -[, only that directory gets included — no subdirectory or subfile would be enrolled in the backup. With -[ you need to list the exact set of files you want to back up. You can totally generate a listing file with the find / -print > somefile command and hand the generated somefile to the -[ option. But heads up: dar will never save files outside the -R given root directory tree, even if some are listed in the somefile file 🦋

-], --exclude-from-file <listing_file>[:eols] — bestie this one is the opposite of -[. Every file listed in listing_file gets excluded from the operation. If a directory is listed in there, then all of its contents are excluded too — the whole tree, bye. This option acts exactly the way the -P option does, and in particular it's compared to the whole path+filename, and it applies to both files and directories. Just like -[, the -] listing file can contain absolute paths, but wildcards are not expanded, neither. 🙈

🔍 File selection in brief

So, as we saw above, the -I -X -P, -g, -[ and -] options are what you use to pick which files get operated on. Here's the tea: -I and -X only ever look at the name of files and they do not apply to directories, while -P, -g -[ and -] look at the filename and the path, so they do apply to directories. ✨

And since version 2.2.0 there are two modes of interpreting these options. The normal original method, and the ordered method:

🌸 The normal method

This is the default, and it's the one we've been describing this whole time:

A directory gets elected for operation if no -P or -] option excludes it. And if at least one -g or -[ option was given on the command line, then one -g or -[ option must cover it, otherwise it does not get elected for operation.
If a directory is not selected, then no recursion happens in it — the directory is pruned, periodt. 🪓
For non-directory files, the same is true (-P, -g, -[ and -] all apply), and a second test must also be satisfied: no -X option may exclude the filename, and if at least one -I option is given, then one of them must match the given filename (with or without wildcards, your call).

👑 The ordered method

This kicks in when the -am option is given on the command line. The ordered method takes care of the order of presence</> between -X and -I on one hand, and of -P, -g, -[ and -] on the other hand. (Heads up: it also has the same action concerning EA selection when you use -u and -U options, but that's no longer file selection, so hold that thought.) In the ordered method, the last argument takes precedence over all the previous ones. Let's take an example:

-X "*.mp?" -I "*.mp3" -I "toto*"

Here dar will include all files except files of name "*.mp?" (those ending with mpX where X is any character), but it will however include those ending with ".mp3". It will also include files whose name begins with toto, whatever they end with. This way, "toto.mp2" will be saved (while it matches "*.mp?" it also begins by toto) as well as "toto.txt" as well as "joe.mp3" (while it matches "*.mp?" it also ends by mp3). But "joe.mp2" will not be saved, because it does not begin by toto, nor ends by mp3, and it matches the "*.mp?" mask. 💀

So as we can see, the last option (-I or -X) overcomes the previous one. -P, -g, -[ and -] act together the same way, but as mentioned above they don't just act on the filename — they act on the whole path+filename. Note that (-g, -P, -[, -]) and (-X, -I) are independent concerning their relative order. You can mix -X -I -g -P -] -[ in any order you want! What matters is the relative positions of the -X options compared to the -I options, and the relative positions of the -g -[ -] and -P options between them. 🦋

In logical terms, if <prev_mask> is the mask generated by all previous masks on the command line, then -I <mask> generates the new following mask: <prev_mask> or <mask>. While -X <mask> generates the new following mask: <prev_mask> and not <mask>. And this is recursive every time you add a -I or -X option. Things work exactly the same with -P, -g, -[ and -] options. 🧠

This ends the file selection explication — let's continue with other options. 💅

-u, --exclude-ea <mask> — do not consider the Extended Attributes (EA) that are matched by the given mask. By default, no EA are excluded, that is if support for EA has been activated at compilation time. This option can be used multiple times. ✨
-U, --include-ea <mask> — do only consider the EA that match the given mask. By default, all EA are included if no -u or -U option is present, and if support for EA has been activated at compilation time. This option can also be used multiple times. See also the -am and -ae options — they apply to -U and -u too — and read below the Note concerning EA. 👀

🧬 Note concerning Extended Attributes (EA)

Support for EA must be activated at compilation time (the configure script tries to do so if your system has all the required support for that). So you can end up with two binaries of dar (same version!), one supporting EA and another which does not. Pro tip: dar -V tells you whether EA support is activated. 👑

The archives they produce are the same and can be read by each other. The only difference is that the binary without EA support is not able to save or restore EAs, but it's still able to test them and list their presence. Slay.

From here on, when we say Extended Attribute (EA) or EA entry, we're only talking about a particular Extended Attribute key and its value. By opposition, the set of all EA associated to a file is designated by "EA set". 📚

Since version 2.3.x the name of EA entries includes the namespace, so that dar is able to consider any type of EA (not only "system" and "user" as previously). Because of this, the two previous options -u and -U have changed and now take an argument which is a mask applied to EA entry names written in the following form: namespace.name, where "namespace" is for example "user". Note that the mask may or may not include the dot (.) and may match an arbitrary part of the EA namespace+name — just remind yourself that masks get applied to the "namespace.name" global string. 🎀

The -am flag here also enables the ordered method, for EA selection too. The ordered versus normal method has been explained above in the file selection note, with some examples using -X and -I. Here it's the same with -U and -u — just replace -X by -u and -I by -U, and the corresponding mask will apply to Extended Attribute selection in place of file selection. 🌈

Another point: independently of the -am option, the -ae option can be used at restoration time only. If it's set, then when a file is about to be overwritten, all EA will be first erased before restoring those selected for restoration in the archive (according to the -U and -u options given). If it's not set, the EA of the existing file will be overwritten, and those extra EA that are not in the archive or are not selected for restoration with regard to the -u and -U options will be preserved. So like — if you haven't used any -u/-U option at backup time and you want to restore from a set of full/differential backups the EA exactly as they were, you have to use -ae, because dar removes the EA before overwriting their set of EA as stored in the archive. Without the -ae option, dar will simply add EA to the existing ones, thus giving you a different set of EA for a given file than the ones recorded at the time of the backup. 😭

Last point: the -acase and -an options alter the case sensitivity of the -U and -u masks that follow them on the command line / in included files, exactly as they do for -I, -X, -P, -g, -[ and -] as well. Very last point ;-) — if the -ac option is used during backup, dar sets back the atime after having read each file (see -aa/-ac options), and this has as a side effect that it modifies the ctime date of each file. But ctime change is what dar uses to detect EA changes. In brief: the next time you back up a file that had to be read (thus whose contents changed), its EA will be saved even if they had not changed. To avoid this side effect, don't use the -ac option if it's not necessary. 💀

This ends the Extended Attribute selection explication — let's continue with other options. 💖

-4 --fsa-scope <family>[,<family>[, ...] — reduce the scope of Filesystem Specific Attributes (FSA) to be considered for the operation. FSA are grouped by family. Current available families are:
- extX — this family takes care of the Linux ext2/3/4 flag attributes set by chattr(1) and read by lsattr(1). Dar only considers flags that it's possible to set or clear by users (or a privileged user): append-only, compressed, no_dump (yes, dar can save files having the nodump flag set and restore them afterward with that flag set! 🤯), immutable, data-journaling, secure-deletion, no-tail-merging, undeletable, noatime-update, synchronous-directory, synchronous-update, top-of-directory-hierarchy. Note that "extx" and "ext" are aliases for this FSA family. And in spite of its name, this family of attributes is not limited to ext2/3/4 filesystems. ✨
- HFS+ — this family takes care of the Mac OS X HFS+ birth date of files, in addition to commonly found dates like atime (last access time), ctime (last meta data change) and mtime (last data change). 🍓
- none — "none" is not a FSA family, but it can be used alone to ignore all FSA families. 🙈

By default no restriction is done and FSA of all families are considered at restoration time, but if a family has not been activated at compilation time a warning is issued for each file that cannot have its FSA restored completely (unless this family is excluded from the scope thanks to the -4 option). At backup time, if an FSA family has not been activated at compilation time, no warning is issued and FSA of that family are ignored. Still at backup time, you can also ignore FSA that have compilation time support by excluding them from the operation thanks to this -4 option.

Example of use: --fsa-scope extX,HFS+

-am, --alter=mask — flips on the ordered mode for masks, bestie 💅. This changes how -I and -X get interpreted, plus -g, -P, -[ and -], plus -Z and -Y, plus -U and -u. It can sit anywhere on the command-line, but it can only show up once — no double-dipping. Scroll up to the file selection in brief paragraph for the full rundown on this one. Also heads up: it has an effect on the --backup-hook-exclude and --backup-hook-include options too.
-an, --alter=no-case — sets the filters to case insensitive mode. This only concerns masks specified after this option (peep the -acase option down below too). It changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U.

⚠️ Warning, and it's a big one: case insensitivity requires interpreting filenames, and that depends on the locale dar is run with (defined by the LANG environment variable). Say you create files with LANG set to fr_FR.UTF-8 and you use non-plain-ASCII characters in the filename — there's a real chance those non-ASCII characters get stored across <em>several bytes</em> in that filename, aka so-called "wide characters". Now if you run dar with LANG set to something else, like ru_RU.koi8r, there's a big chance those wide characters don't map to the same letter, or worse, that they don't match any valid wide character for that locale at all 😭. A filename is always a sequence of bytes and always saved as such, but using --alter=no-case means interpreting that sequence in a way that depends on the given locale (as defined by the LANG environment variable). So dar literally cannot know whether a given file should be read with the fr_FR.UTF-8 locale or with it_IT.iso88591 or ru_RU.koi8r and so on, because that info is just not stored in filenames. So if different locales are in play on your system and you're doing a system-wide backup, using --alter=no-case may lead dar to detect an invalid wide character — and in that case it falls back to a byte-by-byte case sensitivity comparison (ASCII characters), which is probably not what you'd expect at first sight 🙈. Most of the time, an upper case wide character (stored on several bytes) does not match the equivalent lower case wide character (several bytes too) when that case sensitivity comparison is done byte by byte.

-acase, --alter=case — sets it back to case sensitive mode for filters. Every mask after this is case sensitive, all the way to the end of parsing or up to the next -an option, whichever comes first. This changes the behavior of -I, -X, -g, -P, -Z, -Y, -u and -U.
-ar, --alter=regex — makes the filters get interpreted as regular expressions (man regex(7)) instead of the default glob expression (man glob(7)). This modifies the -I, -X, -g, -P, -Z, -Y, -u and -U options that follow, up to an eventual -ag option (see just below). Note that for the -P option, the given mask matches the relative path part of the files' path. Let's take an example: assuming you've provided /usr/local to the -R option, the mask "^foo$" will be replaced internally by "^/usr/local/foo$", while the mask "foo$" will be replaced internally by "^/usr/local/.*foo$". ✨
-ag, --alter=glob — this option returns to glob expressions mode (which is the default) after an -ar option has been used. It applies to any -I, -X, -g, -P, -Z, -Y, -u and -U options that follow, up to an eventual new -ar option (see just above).
-i, --input <path> — available when reading from a pipe (basename is "-" for -x, -l, -t, -d, or for -A when -c, -C or -+ is used). When reading from a pipe, standard input is used — but with this option, the file <path> (usually a named pipe) is used instead. This option is here to receive output from the dar_slave program (check doc/usage_notes.html for examples of use 👀). Note that when --sequential-read is used, dar uses a single pipe and no longer relies on dar_slave; the -i option can be used to tell dar which named pipe to read the archive from, instead of the standard input.
-o, --output <path> — available when reading from a pipe (basename is "-" for -x, -l, -t, -d, or for -A when -c, -C or -+ is used). When reading from a pipe, standard output is used to send requests to dar_slave — but with this option, the file <path> (usually a named pipe) is used instead. When standard output is used, all messages go to standard error (not only interactive messages). See doc/usage_notes.html for examples of use. This option is not to be used in --sequential-read mode. 🚫
-O, --comparison-field[=<flag>] — when comparing with the archive of reference (-c -A) during a differential backup, when extracting (-x) or when comparing (-d), only certain fields get considered. The available flags are:
- ignore-owner — all fields are considered except ownership. This is useful when dar is used by a non-privileged user. It won't consider a file as changed just because of a uid or gid mismatch, and at restoration dar won't even try to set the file ownership.
- mtime — only inode type and last modification date are considered, as well as inode-specific attributes like file size for plain files. Ownership is ignored, permission is ignored. During comparison, differences on ownership or permission are ignored, and at restoration time dar won't try to set the inode permission and ownership.
- inode-type — only the inode type is considered. Ownership, permission and dates are ignored. Inode-specific attributes are still considered (like file size for plain files). So comparison ignores differences for ownership, permission and dates, and at restoration dar won't try to set the ownership, permission and dates.

When no flag is provided to this option, the -O option acts as if the "ignore-owner" flag was set — which is the behavior in older releases (< 2.3.0). Also note that for backward compatibility, the --ignore-owner option still exists, and since version 2.3.0 it's just an alias to the --comparison-field=ignore-owner option. And of course, if this option isn't used at all, all fields are used for comparison or restoration. 💖

-H[num], --hour[=num] — if -H is used, two dates are considered equal if they differ from an integer number of hours, and that number is less than or equal to [num]. If not specified, num defaults to 1. This is used when making a differential backup, to compare last modification date of inodes, at restoration or merging time if the overwriting policy is based on the file's data or EA being more recent, and last, when comparing an archive with a filesystem (-d option). It exists to work around some filesystems (like the Samba filesystem) that seem to change the dates of files after having gone from or to daylight saving time (winter/summer time) 🕐🌸. Note that the -H option has influence on the overwriting policy (see the -/ option) only if it is found before it on the command-line or in an included file (using the -B option).
-E, --execute <string> — bestie, this one runs a whole user command-line for you, launching it between slices. 💅 For reading an archive (so that's the -t, -d, -l or -x commands), the string gets executed before the slice is read — or even before it's asked for. For writing an archive (the -c, -C or -+ commands), it runs once the slice has been completed. And you get substitution macros in that string, because of course you do:
- %% → gets replaced by %
- %p → gets replaced by the slice path
- %b → gets replaced by the slice basename
- %n → gets replaced by the slice number (the one to be read or just written). For reading, dar often needs the last slice, but at the start it literally does not know its number. If it can't be found in the current directory, the user command-line gets called with %n equal to 0. That's the convenient little trick to tell the user command to go provide the last slice. And if after executing the string the requested slice is still not there, dar asks the user (as it usually does) with a message on the terminal. Once the last slice is found, the user command-line is called a second time, with %n equal to the value of the last slice number. 🎀
- %N → the slice number with the leading zero as defined by the --min-digits option. If that option isn't used, %N is equivalent to %n.
- %e → gets replaced by the slice extension (always substituted by "dar")
- %c → gets replaced by the context. There are actually three possible values: "init", "operation" and "last_slice". When reading an archive (testing, extraction, diff, listing, or while reading the archive of reference — see the -F option below), the "init" context takes place from the beginning up to the time the catalogue is retrieved. On a multiple slice archive that corresponds to the last slice request. After that point comes the "operation" context. While creating an archive, the context is always "operation" except when the last slice has been created, in which case the context is set to "last_slice". ✨
- %u → gets replaced by the full URL of the path where the slice is stored

Several -E options can be given, and the given commands get called in the order they appear on the command line and in the files included by -B. Heads up though: having '-E script1 -E script2' is totally equivalent to '-E "script1 ; script2"'. In other words, if script1 fails, script2 will still be executed, and dar only gets notified of the exit status of the last -E option. Exit statuses of the previous -E given commands? Ignored, bestie, ignored. 🙈 If that doesn't match what you need, consider using a single -aduc option (see below). More generally you can use any shell construction in the argument to -E, including parenthesis, || and &&. Those files given to -E are known as DUC files (Dar User Command). See also the environment variable DAR_DUC_PATH in the ENVIRONMENT section at the end of this document. 🦋

-aduc, --alter=duc — so, as described above for the -E option, several -E/-F/-~ options (aka DUC commands) get combined using the shell ";" operator, which ignores the exit status of the first commands and only reports to dar the exit status of the last command — which means all commands always get executed. The --aduc option instead combines the different DUC commands using the shell "&&" operator, which executes the next command if and only if the previous command succeeded. In other words, dar gets notified of an error in any given DUC command, but because of that error not all DUC commands may end up being executed. 💀

--aduc modifies the way the next DUC file is sticked to the previous command — so like, check it:

dar --aduc -E script1 -E script2 ... — this leads libdar to call a shell with the following line: "script1 && script2"
dar -E script1 -script2 --aduc -E script3 ... — this leads libdar to call a shell with the following line: "script1 ; script2 && script3". In other words, if you want to avoid the ";", use --aduc before any -E/-F/-~ option. 👑

-F, --ref-execute <string> — same as -E but it's applied between slices of the reference archive (the -A option). --execute-ref is a synonym. 🫶
-~, --aux-execute <string> — same as -E and -F but applied between slices of the auxiliary archive (the -@ option). 🌸
-K, --key [[<algo>]:]<string>
-K, --key gnupg:[<algo>]:keyid/email[,keyid/email[...]]

In the first syntax, you encrypt/decrypt the archive using the <algo> cipher with the <string> as the pass phrase. An encrypted archive can only be read if the same pass phrase is given (that's symmetric encryption, periodt). The available ciphers are "blowfish" (alias "bf"), "aes", "twofish", "serpent" and "camellia" for strong encryption, and "scrambling" (alias "scram") for a very weak encryption. By default, if no <algo> or no ':' is given, the aes256 cipher is assumed (the default was blowfish up to 2.5.x, just so you know). If your password contains a colon ':' you need to specify the cipher to use — or at least use the initial ':', which is equivalent to 'aes:'. If the <string> is empty, the pass phrase will be asked at execution time. So the smallest argument that -K can receive is ':', which means aes256 cipher with the pass phrase asked at execution time. ✨

Note that giving the passphrase as argument to -K (or -J or '-$', see below) may let other users learn the pass phrase — thanks to the ps or top program, for example. So it's wise to either use an empty pass, which makes dar ask the pass phrase when needed, or use -K (or the -J option) from a Dar Command File (see the -B option), assuming it has the appropriate permission to avoid other users reading it. And for those paranoids that are really concerned about the security of their passwords: having a password read from a DCF is not that secure either, because while the file gets parsed, dar makes use of "unsecured" memory — memory that can be swapped to disk under heavy memory load conditions. It's only when the passphrase has been identified that locked memory (aka secure memory) is used to store the parsed passphrase. So the most secure way to transmit a passphrase to dar, then to libdar, then to libgcrypt, is having dar ask the passphrase at execution time — dar then makes use of secured (locked) memory from the very beginning. 🔥

Since archive format 9 (archives generated by release 2.5.0 and following), at reading time it is not necessary to provide the encryption algorithm used — just the passphrase is required, and dar will figure out which encryption algorithm had been used at archive creation time. You can either omit -K, in which case dar will ask for the passphrase at execution time, or you can use -K <string> in a DCF file as explained above (avoid using -K directly on the command-line). 💖

okay so the second syntax kicks off with the literal word gnupg followed by a colon : — and bestie, the way this works is so clever. Everything after that colon gives you the same set of symmetric encryption algorithms as above, except nobody's typing a passphrase. Instead, libdar picks the passphrase randomly and encrypts it with the public key of whatever target users you listed. And you list them as emails or keyids (keyid support landed in 2.7.0, iykyk) in a comma-separated list. 💅

That random key is the maximum length the cipher algorithms supports — on purpose, to maximize security. Once it's encrypted, it gets tucked at the beginning (unless you used the -at option, sneaky) and at the end of the generated archive. Then at reading time, only the listed user(s) can read that archive, thanks to their own private key. 🔑

This whole feature comes with receipts though — it assumes everybody involved (the archive creator and the target users) has their GnuPG key-ring set up properly. Specifically:

the archive creator must have validated the public keys of the target users
the target users must actually own the corresponding private key in their key-ring

Like, example time bestie: using --key gnupg::bob@nowhere.org,joe@somewhere.com generates an aes256 encrypted archive whose passphrase was randomly chosen by libdar and encrypted with the public keys of bob@nowhere.org and joe@somewhere.com. Want blowfish instead of aes256? Easy: --key gnupg:bf:bob@nowhere.org,joe@somewhere.com. ✨

More generally with GPG, note that users have the duty to validate/certify that a given key-pair is really owned by the physical person you expect it to have. And no, you don't get to just vibe-check it — this has to be done by checking the key fingerprint through a secure means (face to face, a phone call if you trust that channel enough not to be intercepted and deep faked, or some other already-trusted communication means...). See also the --sign option below. 👀

Note that if you've set a passphrase on your private key, dar will ask you for it dynamically, which means dar has to be run from a terminal. There is no other way provided to transmit a private key's passphrase to libdar. So if you wanna use dar/libdar in scripts and make use of the public key algorithm, you should avoid setting a passphrase on the private key you want to use. See also GNUPGHOME in the ENVIRONMENT section at the end of this document. 🫶

Obvious but important! To read a gnupg encrypted archive, you need your private key — not just the passphrase to activate it, if one is set. So if you're planning to back up your system and encrypt that backup with gnupg, you should have a copy of this private key available outside of the archive (usb key, floppy, CD/DVD, ...) so you can actually restore your backup! 💀

-J, --ref-key [[<algo>]:]<string> — same meaning/use as the -K option's first syntax, but this given key is used to decrypt the archive of reference (the one you hand over with the -A option). --key-ref is a synonym. Note that for archives generated using dar release 2.5.0 and above, this option is no longer necessary — unless you wanna give the passphrase on the command-line (not recommended, bestie, please) or in a DCF file (which file would be set with restricted access permissions and/or ACL).
-$, --aux-key [[<algo>]:]<string> — same as -J but for the auxiliary archive of reference (the one given with the -@ option). Here too, this option is no longer necessary to read archives generated by dar release 2.5.0 and above. ✨
-#, --crypto-block <size> — so to be able to randomly access data in an archive, it isn't encrypted globally but block by block. You can define the encryption block size with this argument, which defaults to 10240 bytes. Note that the syntax used for the -s option is also available here (k, M, G, etc.). Note also that crypto-block is stored as a 32 bits integer, thus a value larger than 4GB will cause an error. Note last, that the block size given here must be provided when reading this resulting archive — using the -* option if the archive is the archive of reference (given to -A), using -% options if the archive is the auxiliary archive of reference (given to -@), or using this -# option if it is the subject of the operation (listing, comparing, testing that archive). If the value is not the default and the value you give isn't correct in regard to the value given at archive creation time, the archive will not be possible to decrypt — so it's safer to keep the default value (and not use the -#, -*, -% options at all). 🙈
-*, --ref-crypto-block <size> — same as --crypto-block but to read the archive of reference (-A option). --crypto-block-ref is a synonym.
-%, --aux-crypto-block <size> — same as --crypto-block but to read the auxiliary archive of reference (-@ option).
-e, --dry-run — Do not perform any action (backup, restoration or merging), and instead displays all messages as if it was for real (a "dry run" action). The --empty option is a synonym. 🎀
-aSI, --alter=SI[-unit[s]] — when using k M G T E Z Y prefixes to define a size, use the SI meaning: multiple of 10^3 (a Mega is 1,000,000).
-abinary, --alter=binary[-unit[s]] — when using k M G T E Z Y prefixes to define a size, use the historical computer science meaning: multiple of 2^10 (a Mega is 1,048,576).

The --alter=SI and --alter=binary options can be used several times on the command line. They affect all prefixes which follow, even those found in files included by the -B option, up to the next --alter=binary or --alter=SI occurrence. Note that if in a file included by the -B option, an --alter=binary or --alter=SI is encountered, it affects all the following prefixes, even those outside the included files. For example, when running with the parameters -B some.dcf -s 1K, 1K may be equal to 1000 or 1024, depending on --alter=binary or --alter=SI being present in the some.dcf file. By default (before any --alter=SI/binary option is reached), binary interpretation of prefixes is done, for compatibility with older versions. 🦋

-ac, --alter=ctime — When reading a filesystem (during a backup or comparison), restores the atime of all files to what it was before the file was read. This makes it appear as if it had not been read at all. However, because there is no system call to let applications change the ctime (last inode change) of a file, setting back the atime results in the ctime being changed (hence the alter=ctime). Some recent unix systems allow an application to get 'furtive read mode' to the filesystem (see below). On older systems, however, for most users, having the atimes of the files changed shouldn't be a problem, since they can be changed by any other program (running by any user!) as well (like the content-index program Beagle). Ctimes on the other hand, are the only way for security software to detect if files on your system have been replaced (by so called root-kits mostly). This means that should you run dar with -ac, security software which uses ctimes to check will mark every file on your system as compromised after the backup. In short, this means this option should only be used by people who know what they are doing. 👑

It's the opinion of this writer that any software susceptible to atime changes is flaky or even broken (because of the aforementioned reasons why atimes can change). But, that doesn't take away that there are programs who rely on atimes remaining the same, like Leafnode NNTP caching software. Therefore this option exists. 💖

-aa, --alter=atime — okay so when you pass -aa (and not -ac, bestie, they're opposites 💅), the atime of every file and directory that gets read is updated, and the ctime stays exactly the same. And here's the tea: dar itself does nothing with atimes and ctimes — it just lets the system do its little job of updating atimes when files are accessed for reading. Which is, like, literally what atimes and ctimes were meant to represent in the first place, so ✨correct✨. This is dar's default (ever since version 2.4.0), unless 'furtive read mode' (coming right up, keep reading) is supported by your system and dar got compiled with that support activated.

Furtive read mode is the mode where neither atime nor ctime get modified while dar reads each file and directory. Bonus side quest: better performance, because nothing has to be written back to disk 🎀. A known Unix kernel that supports this feature is Linux 2.6.8 and above — and the support also has to be present in your system's standard C library for dar to be able to activate it at compilation time. When this feature is on, it becomes dar's default behavior for super user; for everybody else the default is -aa. But if you're root and you do not want "furtive read mode" (even though it was activated at compilation time), you can just say either -aa or -ac and call it a day. 🫶

-at, --alter=tape-marks — for archive creation and merging, the default behavior (since release 2.4.0) is to sprinkle escape sequences (aka tape marks) followed by inode information all along the archive. If you give -at instead, dar will not add that info to the archive — which gives you a slightly smaller archive and a faster backup, at a cost, so listen up. When reading an archive, the default behavior is to ignore these escape sequences entirely and rely on the catalogue sitting at the end of the archive instead. But if --sequential-read is given on the command line (see below 👀), dar skips the catalogue at the end and leans on those escape sequences to figure out what's in the archive — which means a sequential reading of the archive, an operation that's suitable for tape media.

Heads up: it is not recommended to disable escape sequences (aka tape marks) with -at unless you care way more about the resulting size and execution speed of your backup (especially if you've got a ton of small files) than about being able to recover your data if the archive ends up corrupted or only partially written. 😭

Without escape sequences, dar cannot sequential read an archive — and that's the only way (besides using an isolated catalogue) to use an archive that has a corrupted catalogue or has no catalogue at all, which is exactly what happens if a system crash hit during archive creation or if there wasn't enough disk space to complete the archive. 💀

-0, --sequential-read — this changes dar's behavior when reading an archive. By default, the traditional way is used, which relies on the table of contents (aka "the catalogue") located at the end of the archive. With --sequential-read instead, dar relies on escape sequences inserted all along the archive with each file's inode information. This leads to a sequential reading of the archive, an operation suitable for tape medium 🎀. However — this feature is only available for archive format starting revision "08" (i.e.: since release 2.4.0) and only if -at has not been used during archive creation or merging.

This option is available for archive testing (-t), comparison (-d), restoration (-x), listing (-l), and to read the archive of reference (-A option) for isolation (-C) and archive creation (-c). And ngl, sequential reading of an archive is always much slower than the usual reading method, so don't reach for this option unless you really need it. 😌

-9, --min-digits <num>[,<num ref>[,<num aux>]] — by default the slice number inside a filename has no padded zeros, which means that when you sort a directory's contents alphabetically you end up reading all the slices starting with '1', then all the ones starting with '2'. Like: slice 1, 10, 11, 12, 13, ... 2, 20, 21, 23, ... etc. And dar is absolutely not bothered by this display situation, but some users would like their slices sorted in actual order, and honestly? Fair. ✨

That's why --min-digits exists: it lets you ask dar to prepend enough zeros to the slice number so it's as wide as the argument you pass. So if you hand it 3, dar stores the slice number as 001, 002, 003, ... 999. And then, well, the next slice is 1000, so the alphabetical sorting order gets broken all over again 😭. You're thus advised to pick a number big enough to cover the number of slices you expect to use.

Before release 2.7.0, when reading an archive you were also required to provide this same argument, otherwise dar couldn't find the slice. Since 2.7.0, dar auto-detects the min-digits value to use — unless there's a mix of archives with the same basename but different min-digits. In that conflicting context, you have to bypass the min-digits auto-detection mechanism and specify which min-digits value to retain in order to read the archive, eventually followed by a comma and the number of digits to use to read the archive of reference (given to the -A option), eventually followed by a comma and the number of digits to use for the auxiliary archive of reference (given to the -@ option). 💅

--pipe-fd <num> — this will read further arguments from the file-descriptor <num>. The arguments read through this file-descriptor must follow a TLV (Type/Length/Value) list format. This option is not intended for human use — it's for other programs launching dar, like dar_manager. It got added to overcome the command line length limit. 🤖
-al, --alter=lax — when reading an archive, dar will try to workaround data corruption of the slice header, archive header and catalogue. This one is the last resort solution for when you're staring down media corruption, bestie. And it is rather — and still strongly — encouraged to test your archives before relying on them, as well as using Parchive to do parity data of each slice, so you can recover data corruption in a much more effective manner and with way more chance of success. 🌈

Dar also has the possibility to backup a catalogue using an isolated catalogue — but that does not face slice header corruption, or even saved file's data corruption (dar will detect such an event but will not correct it). 😬

-G, --multi-thread { <num> | <crypto>,<compression> } — when libdar is compiled against libthreadar, it can make use of several threads 🧵✨. If the argument is two numbers separated by a comma, the first defines the number of worker threads to cipher/decipher, and the second the number of threads to compress/decompress. If the argument is a single number (-G <n>), it's equivalent to giving that number as the number of compression threads and giving 2 for the ciphering threads (-G 2,<n>).

Using multi-threading at archive creation time means relying on per block compression rather than the legacy streaming compression — and if the block-size isn't specified (see the -z option for details) it defaults to 240 KiB. Not providing any -G option at all is equivalent to providing -G 2,1 when libthreadar is available, else -G 1,1. And one more thing: if an archive was created with streaming compression, the decompression cannot use multi-threads — the deciphering, though, can always use multiple threads. 👑

-j, --network-retry-delay <seconds> — when a temporary network error happens (lack of connectivity, server unavailable, and so on), dar does not give up — it waits a bit, then retries the failed operation. This option is here so you can change that default retry time, which is 3 seconds. If you set it to zero, libdar will not wait but rather ask the user whether to retry or abort in case of network error. 🦋
-afile-auth, --alter=file-authentication — okay so picture this: you're reading or writing an archive to a remote repository (SFTP or FTP) and no password was provided. Normally dar would just pop up and ask you interactively, but with this option it doesn't. Instead, when you're relying on the FTP protocol, dar checks the ~/.netrc file for credentials. 🕵️‍♀️ And if it's SFTP instead? This option makes dar first try to connect using public key authentication instead of password authentication. And if that key could not be loaded, bestie, it will ask you for the key's passphrase interactively. 🔑 No sneaking around it.
-ab, --alter=blind-to-signatures — dar does not check whether an encrypted archive with public key that has also been signed actually has the correct signatures. It's giving "nothing to see here" energy, which is exactly what it says on the tin. 🙈

💾 SAVING, ISOLATION, MERGING AND REPAIRING SPECIFIC OPTIONS (to use with `-c`, `-C`, `-+` or `-y`) 💾

These ones only make sense when you're in save / isolate / merge / repair mode, k? Let's go. 🫶

-z, --compression={ [algo] | level | algo:level | algo:level:block-size } — adds compression within slices. If you don't pass -z at all, no compression happens, periodt. But if you pass -z without naming an algorithm, gzip is assumed. 🎀
- algo: the values you can use are "gzip", "bzip2", "lzo", "xz", "zstd" or "lz4". That's the whole menu. ✨
- level: the compression level, an integer from 1 to 9 — except for zstd, which ranges from 1 to 22 — is optional, and is 9 by default. Heads up tho: when you're using the xz algorithm, it's better to specify a compression ratio less than or equal to 6 so you don't hit important memory requirements. 😭 A ratio of 1 means less compression and faster processing, while at the opposite end a ratio of 9 gives the best compression but the longest processing time. Trade-offs, bestie, always trade-offs.
- block-size: if you set it to zero (which is also the default value), you get the legacy (and performant) "streaming compression" mode — the only one available up to release 2.7.0. Since then, the "block compression" mode gives you the ability to leverage multi-threading (see the -G option) by compressing per block and handing different blocks to different threads. 🧵 The larger the block, the better the compression ratio gets (it tends to be as good as the streaming compression mode's ratio when block size increases), but files smaller than a block size can only be processed by a single thread. Memory requirement also increases by the product of the block size times the number of threads. And last — a too-small block-size will cost more CPU cycles (the multi-threading management overhead becomes important compared to the effective compression processing) and, independently, short blocks give poor compression rates. So it is advised to use values at least greater than 50 ~ 100 KiB (you can use the k, M, G, ... suffixes described for the -s option). If the block-size is not specified and the given -G option leads to a number of compression threads greater or equal to 2, a block-size of 240 KiB is used. If you want the legacy streaming compression: do not use the -G option (or use it specifying only 1 compression thread) and do not set the compression block size (or set it to zero). 💅

Valid usage of -z is for example: -z, -z9, -zlzo, -zgzip, -zbzip2, -zlzo:6, -zbzip2:2, -zgzip:1, -zxz:6, -zlz4::10k -z::12000 -zbzip2:8:10k and so on. Usage for the long option is the same: --compression, --compression=9, --compression=lzo, --compression=gzip, --compression=bzip2, --compression=lzo:6, --compression=bzip2:2, --compression=gzip:1 --compression=xz:9 and so on. 🌈

About lzo compression — and this is the tea 🍵 — the compression levels of dar and the lzop program do not match. If you want to get the behavior of compression level 1 of lzop, use the lzop-1 algorithm in place of lzo with dar/libdar. If you want the behavior of lzop compression level 3, use the lzop-3 algorithm in place of the lzo algorithm. Lzop compression levels 2, 4, 5 and 6 are the same as level 3. And last, there is no difference about compression level 7, 8 and 9 between dar and lzop. Also: the lzop-1 and lzop-3 algorithms do not make use of any compression level (the compression level is ignored with these algorithms). Iconic naming chaos, no cap.

-s, --slice <number> — the size of the slices, in bytes. If the number is appended by k (or K), M, G, T, P, E, Z, Y, R or Q, the size is in kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, zettabytes, yottabytes, ronnabytes or quettabytes respectively. 🌸 Example: "20M" means 20 megabytes, which by default is the same as giving 20971520 as argument (see also the -aSI and -abinary options). And if -s is not present, the backup will be written to a single slice whatever the size of the backup may be (assuming your operating system can support arbitrarily large files, which, slay). 👑
-S, --first-slice <number> — -S gives the size of the first slice, which may be chosen independently of the size of the following slices (either bigger or smaller). This option needs the -s option. And by default of the -S option, the size of the first slice is the same as the one of the following slices. 🎯
-p [<integer>], --pause[=<integer>] — pauses before writing to a new slice (this requires -s). By default there is no pause at all — all slices get written in the same directory, up to the end of the backup or until the filesystem is full. In that latter case, the user is informed of the lack of disk space and dar stops for user action. As soon as some disk space becomes available, you can continue the backup. 🫡 The optional integer this option can receive tells dar to only pause every n slice. Giving 3 for n will make dar pause only after slices 3, 6, 9 and so on. If this integer is not specified, the behavior is as if 1 was given as argument, which makes dar pause after each slice.
-D, --empty-dir — At backup time only: when excluding directories either explicitly using -P or -] options, or implicitly by giving -g or -[ options (a directory is excluded if it does not match the mask given with -g options or -[ options), dar does not store anything about these. But with the -D option, dar stores them as empty directories. 🎀 This can be useful if you're excluding a mount point (like /proc or /dev/pts). At restoration time, dar will then recreate these directories (if necessary). This option has no meaning with -C and is ignored in that case. Independently of that, -D can also be used at restoration time, but it activates a slightly different feature (see RESTORATION SPECIFIC OPTIONS below). 👀
-Z, --exclude-compression <mask> — filenames covered by this mask are not compressed. It is only useful in conjunction with the -z option. By default, all files are compressed (if compression is used). This option can be used several times — in that case, a file that matches one of the -Z masks will not be compressed. The argument given to -Z must not include any path, just the filename (eventually/probably using wildcards). And this option, used while merging or repairing, allows you to change the compression of files. 🦋
-Y, --include-compression <mask> — filenames covered by this mask (and not covered by masks given to the -Z option(s)) are the only ones to be compressed. It is only available with the -z option. By default all files are compressed. This option can be used several times — in that case all files that match one of the -Y masks will be compressed, if they do not also match one of the -Z masks. The ordered method here applies too when activated (with the -am option); it works exactly the same as the -I and -X options, but applies to file compression, not file selection. In other words, it matches only on the file name, not on the path of files. 💅 This option, used while merging or repairing, allows you to change the compression of files. ✨
-m, --mincompr <number> — files whose size is below this value will not be compressed. If -m is not specified it is equivalent to giving -m 100 as argument. So if you want to compress all files whatever their size is, you need to type -m 0 on the command line. The size unit is the byte (octet), and the same number extensions as those used with -s or -S are available here too, if you want to specify the size in kilobyte, megabyte, gigabyte etc. 🍓
-1, --sparse-file-min-size <number> — set the minimum run of zeroed bytes that dar is allowed to swap out for a "hole". Default is on, at 15 bytes. Wanna fully kill it? Set the size to zero. Doing that gives you a genuinely noticeable speed boost but probably makes your archive a lil bigger (depends on what your data looks like, bestie).

So what even is a sparse file? It's a file with holes in it 🕳️. On a filesystem, a chunk of zeroed bytes just... doesn't get stored on disk, so an enormous file that's mostly zeros might only eat a few bytes of actual disk space. And here's the tea: dar literally cannot see how any given file is allocated, because it works at a filesystem-abstraction level (it doesn't know how any particular filesystem is implemented, which is exactly why it's portable). BUT when it spots a run of zeroed bytes bigger than the threshold you gave it, it can assume it's found a hole. So instead of storing those zeroed bytes, it drops a tag next to the saved data recording the size of the hole — and therefore where the next non-zeroed bytes go. Result: dar archives take up way less disk space when a sparse file shows up. Iconic 💅.

At restoration time, dar restores the holes by writing normal data and seeking over the hole to write the next normal data after each hole. If the underlying filesystem supports sparse files, the holes come back. And note: applications can't tell the difference between a sparse file and a normal one, so dar may happily turn normal files into sparse files and vice versa — only the disk requirement changes. Last thing, and it matters: even though dar can shrink an archive with holes as small as 15 bytes (smaller values work too, but the overhead ends up costing more than just storing those zeroed bytes normally), it might not work out the same at restoration, because filesystem allocation units are usually several kilobytes (a page). However — and this is the comfort — a restored file will never be larger than it would have been without holes. The only downside of this whole feature is the extra CPU cycles it burns. 🫶

-ak, --alter=keep-compressed — during merging and repairing, keep files compressed. This comes with several restrictions, so listen up: -z, -Z, -Y, and -m are ignored, and if two archives have to be merged, both of them must use the same compression algorithm — or one of them must not use compression at all (this last restriction will probably disappear in a next version, no cap). The payoff is a greater speed of execution, since compression is usually CPU intensive. 🔥
-ah, --alter=holes-recheck — for merging and repairing, the sparse file detection mechanism is disabled by default. But if you wanna activate it (say you've got an old archive you want to convert to the current archive format with sparse-file care taken), you need the -ah option to switch sparse file detection back on. Then, for merging and repairing, --sparse-file-min-size can be used exactly as described above for archive creation. Bonus move: you can have files stored as sparse files in the archive of reference end up stored as normal files in the merged archive, by using -ah and passing to --sparse-file-min-size a value larger than all your file sizes. For example, as of today in year 2018, passing -ah --sparse-file-min-size 1E (1E being one exabyte) should be large enough. 😌
--nodump — do not save files that have the 'd' flag set (see chattr(1), lsattr(1), ext2 commands). Heads up though: this option may not be available if the system dar was compiled on didn't provide support for ext2 flags. Also note that this option does nothing with the -+ option (merging), because no filesystem is used for that operation. 🙈
-5, --exclude-by-ea[=<extended attribute name>] — exclude inodes from the backup that have been set with the EA you pass as the argument. If no argument is given to the option, the default EA used to exclude files from backup is "user.libdar_no_backup". To set this attribute on a given file, use:

setfattr -n user.libdar_no_backup <filename>

To remove it:

setfattr -x user.libdar_no_backup <filename>

And last, to check the presence of this EA:

getfattr <filename>

-M, --mount-points={ I:<path to fs> | X:<path to fs> } — if the argument is in the I:<path to fs> form, the filesystem that this path points to is considered for the backup operation — meaning other file filtering mechanisms get applied to it and some or all files of that filesystem will be saved for backup. With the X:<path to fs> form, no file in that filesystem will even be considered for backup. Both the X: and I: forms must be given an absolute path. The -M option can be used several times on the command-line. If only I: forms are used, the filesystem based filtering behaves like a white list (only those listed paths are included). If only the X: form is used, it behaves like a black list (everything is considered except those listed paths). And if you mix I: and X: forms, the filesystems considered for backup will be the ones given with an I: form and not also given with an X: form.

Okay important vibe check: this is filesystem based filtering, not path based. So if, for example, a filesystem is mounted under /var and you specify I:/var/log, the entire /var filesystem gets considered for backup. If you'd rather only save what's inside /var/log, use the -P/-g/-X/-I/-[/-] options, which do file filtering by name and path+name. Also: you cannot exclude the filesystem that contains the path given to the -R option. Using -M with an argument erases any previous configuration done with -M without an argument (see below), and vice versa. By default (no -M option specified), no filtering based on filesystem is performed — in other words, all files are considered for the other file filtering mechanisms (in particular the -P/-g/-X/-I/-[/-] options) and eventually backed up.

example of use:

-MI:/var -MX:/var/spool
--mount-points=I:/var --mount-point=X:/var/spool

-M, --no-mount-points — this is the legacy form of the option described just above, the one that existed before release 2.7.0. When -M is provided without an argument, only files located on the filesystem pointed to by the path given to the -R option will be considered for backup. Subdirectories that are mounting points for other filesystems will not be saved (or will be saved empty if the -D option is used). This option is useless and ignored for merging operation. And using -M without an option leads dar to ignore any previous -M I:<path> and -M X:<path> options that could have been given on the command-line or in a -B included file so far. 💀
-,, --cache-directory-tagging — don't save the contents of directories that use the Cache Directory Tagging Standard. See http://www.brynosaurus.com/cachedir/spec.html for details. (this option is useless with the -+ option) 🎀
-/, --overwriting-policy <policy> — this one lets you define when or how file overwriting can happen at restoration or archive merging time. It does not apply to slice overwriting (that's driven by the -n option instead) — it applies to files during extraction, and to files inside archives when you're merging two of them. When we talk about overwriting, a file is said to be 'in place' while another is known as 'new' or 'to be added'. At restoration time, the 'in place' one is the file present in the filesystem, while the 'to be added' one is the file from the archive. At merging time, the 'in place' one is the one from the '-A' archive of reference, while the 'to be added' one is the one from the auxiliary '-@' archive or reference. And just so you know: this option does not apply to archive repairing.

Also, the moment you use the -/ option, -n only applies to slice overwriting, and the -r, -k and -ae options are ignored (those are restoration specific options). ✨

Okay so bestie, the <policy> argument? It’s literally composed of actions and eventually of conditional expressions too. 💖 Actions are the whole blueprint for solving an overwriting conflict — one side is the file’s data, the other side is the file’s Attributes (Extended and Filesystem Specific). So an action is a lil couple: one action for Data and one for EA+FSA. Actions for Data are represented by uppercase letters, while actions for EA+FSA are defined by lowercase letters. And both actions are independent of each other, no cap:

P — means ‘Preserve’ 💅. When merging two archives, the data of the resulting archive will be taken from the ‘in place’ file. While when extracting, the data of the inode in filesystem will be preserved (thus no overwriting will occur for the data). Periodt.
O — means ‘Overwrite’ 🔥. When merging two archives, the data of the resulting archive will be taken from the ‘to be added’ file. While when extracting, the data of the inode in filesystem will be overwritten by data from the archive.
S — means ‘mark Saved and preserve’ ✨. When merging two archives, the data of the resulting archive will be marked as already saved in the archive of reference (making thus a differential archive, even if none of the original archives were differential archives). All data will be dropped in the resulting archive, but the last modification date [aka mtime] (used to detect change in file’s data) will be taken from the ‘in place’ file. This action does not apply when extracting files, it is thus considered equal to “Preserve” (P) in that situation. 😌
T — means ‘mark Saved and overwrite’ 💥. When merging two archives, the data of the resulting archive will be marked as already saved (same as S action): all data will be dropped in the resulting archive, however the last modification date [aka mtime] (used to detect changes in a file’s data) will be taken from the ‘to be added’ file. This action does not apply when extracting files, it is thus considered equal to “Overwrite” (O) in that situation.
R — means ‘Remove’ 💀. When merging two archives, the resulting archive will not contain any entry corresponding to the file that were in conflict. This also implies that no EA will be stored for that particular entry as the entry will no more exist in the resulting archive (as if it had never yet existed). When extracting files, this will lead to file’s suppression. Dramatic? Yes. Accurate? Also yes.
p — means ‘Preserve’, same as P (but lowercase letter) — preserve the whole EA set and FSA 🎀. When merging two archives, the Attributes set of the resulting file will be the ones of the ‘in place’ file (whatever is the overwriting action taken for its data). While when extracting files to filesystem, the Attributes of the file in filesystem will not be changed (whatever is the overwriting action taken for its data, unless the file is removed using the R policy, which would remove the inode and thus also any Attributes it had). Careful, bestie.
o — means ‘Overwrite’, same as O (but lowercase letter) — overwrite the whole EA set and FSA 🌸. When merging two archives, the Attributes set of the resulting file will be taken from the ‘to be added’ file. While when extracting files, the Attributes set of the file in the filesystem will have its Attributes erased and replaced by those of the file in the archive (still independent of what overwriting action is taken for file’s data).
s — means ‘mark Saved and preserve’, same as S (but lowercase letter) for EA and FSA instead of data 🦋. When merging two archives, the EA and FSA of the resulting file are marked as already saved in the archive of reference, thus they are dropped but the date of last inode change [aka ctime] (used to detect changes in file’s EA and FSA) will be taken from the ‘in place’ file. This action does not apply when extracting files, it is thus considered equivalent to “Preserve” (p) in that situation.
t — means ‘mark Saved and overwrite’, same as T (but lowercase letter) for EA and FSA instead of data 💜. When merging two archives, the EA and FSA of the resulting file are marked as already saved in the archive of reference, thus they are dropped but the date of last inode change [aka ctime] (used to track changes in EA) will be taken from the ‘to be added’ file. This action does not apply when extracting files, it is thus considered an equivalent to “Overwrite” (o) in that situation.
m — means ‘merge Attributes and preserve’ 🧚. The resulting file in the merged archive will have Attribute entries from both the ‘in place’ and the ‘to be added’ files. If both files share a same Attribute entry (same FSA or for EA the same key for a given association) the one of the ‘in place’ file is kept (where from the ‘preserve’ notion). When extracting a file, the file in the filesystem will have its EA and FSA set enriched by the ones of the file in the archive that do not exist on filesystem, but its already existing Attributes will stay untouched.
n — means ‘merge Attributes and overwrite’ 🌈. The resulting file in the merged archive will have Attribute entries from both the ‘in place’ and the ‘to be added’ files. If both files share a same Attribute entry (same FSA or for EA the same key for a given association) the one of the ‘to be added’ file will be kept (where from the ‘overwrite’ notion). When extracting file, the file in the filesystem will have its Attributes set enriched by ones of the file in the archive with some of them possibly been overwritten.
r — means ‘remove’, same as R but for the Attribute set (thus all EA and FSA entries) of a given file (r is lowercase letter here) ⚠️. The file of the resulting archive during merging operation will not own any EA nor any FSA, even if the ‘in place’ and/or the ‘to be added’ files did have some. For file extraction, this means that the file in the filesystem will lose all its EA set. The FSA cannot be ‘removed’ from a filesystem and may not always have a default value, thus this action does not modify FSA at all in case of archive extraction. But in case of merging the FSA are removed as previously described. As for all the previous tests, this Attribute operation is independent of the operation chosen for file’s data (uppercase letters).
d — means ‘delete’ 😭. When a same EA or FSA entry is found both in the ‘in place’ and ‘to be added’ files, such entry will be absent in the resulting archive. In other words, when merging, the EA set and FSA will only contain EA and FSA entries specific to the ‘in place’ and those specific to the ‘to be added’ file. Entries in common will not be present. When extracting a file from an archive, the file on filesystem will have its EA set enriched by entries of the ‘to be added’ file that are new to the ‘in place’ file. The other EA entries (which are thus present in both archive and filesystem) will be removed from the set, while the other FSA will stay untouched (FSA cannot be “removed” from a filesystem, nor they always have a default value).

* — valid for both EA and data, bestie. It's giving "not decided yet 💭": the action isn't defined at this step of the evaluation and further evaluation is required (peep the 'chain' operator below, iykyk).

A — means 'Ask for user decision' 🙋‍♀️. This uppercase letter is all about Data overwriting. An application interaction lets the user define the action for each file in conflict. Note that this action, if used alone, may become very boring or painful 😭. The whole idea is to use it inside conditional statements (described below) so dar only asks about the non-obvious cases. Main character energy: only show up when it matters.

a — also means 'Ask for user decision' 🙋‍♀️, but lowercase. This one is the equivalent for EA and FSA of the A action. Same deal: intended to be used in those same conditional statements described below.

An action is thus a couple of letters 💅, the first being uppercase (for the file's data), the second being lowercase (for the file's EA and FSA). When the -/ option is not given, the action is equivalent to -/ Pp, which makes dar proceed to file, EA and FSA preservation ✨. Before release 2.4.0 (June 2011), only -n and -w options were available to define the overwriting policy, and the default behavior was to warn and wait for confirmation before overwriting — that behavior can be set by the -/ Oo policy. It seems the default behavior changed to -/ Pp at that time and nobody complained or noticed the difference until 2023 😭, so this default behavior will not be reverted, as nobody complained for more than 12 years about that. Periodt.

Here follow some examples of actions — all of these are done for any entry found in conflict during archive merging or archive extraction. We will see further down how to define conditional actions 🦋.

-/ Rr — will lead dar to remove any file from filesystem that ought to be restored(!) 💀. Note the action for EA/FSA is useless here: the EA and FSA will always be erased as well as data using R. Thus -/ Rp would lead to the same result.
-/ Po — will keep data of the 'in place' file and EA and FSA set from the 'to be added' file. Mix and match, slay 💅.
-/ Ss — using this option when merging an archive with itself (used both as archive of reference (-A option) and auxiliary archive of reference (-@ option)) will provide the same action as an archive isolation of the archive of reference, but using twice more memory (so keep using the isolation operation as before! Here this is just an illustration of the possibility 🙈).

As seen previously, the -u and -U options can be used to filter which EA entry to consider and which to ignore. The question here is to explain how this filtering mechanism interacts with the different policies we just presented above 👑.

For files that are not in conflict (found only as 'in place' or as 'to be added'), only the EA entries matching the EA filter are kept.
For files in conflict, the overwriting policy is evaluated first, then the filtering mechanism is applied after it.

Thus, for example, using the following [ -/ "Po" -u "*test" ], when merging two archives, only EA ending with "test" will be retained, and when a conflict takes place, this "test" ending EA will be taken from the 'to be added' file if it has some EA of that type, its other EA entry will be ignored as well as any EA entry of the 'in place' file — even those ending by "test" 😭. At restoration, using the same options, files without conflict will get restored but only EA entry ending with "test" will be restored, and for files with conflict (already present in filesystem), the EA set of the file in filesystem will be removed and replaced with the EA entries of the file in archive that ends by "test", if some exist ✨.

The situation is similar with FSA family scope and overwriting policy. Only FSA of a family present in the scope will be retained; the overwriting policy acts first, then the FSA scope is applied. Note however that any FSA present on filesystem and excluded from the FSA scope are not touched 🫶.

Well, now let's see how to bring some more fun using conditional statements in all these actions 🌈. The structure to use is the following:

{<condition>}[<action if condition is true>]

This syntax lets you place an action (like the ones we saw just above) inside the brackets [ and ] (for example [Pp]) that will take effect only if the evaluation of the <condition> is true. Stated that such a statement is a new type of action, you may have guessed that you may use it recursively: {<condition1>}[{<condition2>}[<action>]) 🧚.

Well, so far it seems useless. But instead of the "if <condition> then <action> else <action>" paradigm common to programming languages, due to the command line context it has been chosen to instead use an implicit "OR" operator between actions 💅. Thus you can "stack" conditional statements this way:

{<condition1>}[<action1>] {<condition2>}[<action2>] <action3>

In this example, if <condition1> is true then <action1> will be used, ELSE if <condition2> is true then <action2> will be used, ELSE <action3> will be used. This leads to the same possibilities as what is available with programming languages, but with a slightly more simple syntax 👑. Seen this, the recursion of conditional syntax is more interesting. For readability, you are allowed to add any space or tab in the overwriting policy, but the resulting overwriting policy must be given as a single argument to dar, thus the use of quotes (either simple ´arg´ or double "arg") is necessary 🔥.

The last operator we will see is the 'chain' operator ⛓️. Once an expression is evaluated, the resulting couple of action may contain an * (undefined action for EA or data). Further evaluation must be done. The chain operator, which is represented by a semicolon ;, lets one separate several independent expressions that will be evaluated in turn up to the time the couple of action is fully defined ✨.

Once an action (for EA or for Data) is defined, it can be redefined by a subsequent evaluation in the chain — however if the action is defined it cannot be set back to undefined, thus * will never overwrite a previously defined action 🚫. If at the end of the policy the couple of action is not fully defined, the 'preserve' action is used (P or p depending on which of EA or Data is left undefined). Here follow a example of syntax:

-/ "{<condition1>}[P*] O* ; {<condition2>[*p] *o} ; Rr"

The first expression will evaluate to either P* or O*. At this step, as the action is not completely defined, the second part of the chain is evaluated. It will end with either *p or *o. In any case, we have after this second statement of the chain a fully defined action for both data and EA (either Pp, Po, Op or Oo) 💖. Thus the evaluation stops here and the "Rr" policy will never be evaluated 🎀.

okay so bestie, the very last thing we gotta peek at before you're fully fluent in dar's whole vibe are the conditions — like, what you can put between those curly braces '{' and '}'. 💅

Each condition is defined by a letter, and sometimes that letter gets an argument in parenthesis right after it. You got your usual logical operators: negation (!), conjunction (&), and disjunction (|). But heads up: these characters must be escaped or quoted so your shell doesn't try to interpret them when you're on the command line. Especially that ! — under most shells you gotta quote and escape it, like -/ '{\!R}[..]..'. The escape character '\' isn't needed inside DCF files (the ones you hand to the -B option) because no shell is interpreting those files. 🐚

And then there's a new operator on the block: the "inversion" operator, written '~'. Like negation, it's unary, but unlike negation it flips the roles of 'in place' and 'to be added' for the evaluation — which is slightly different from just taking the negation of the result. 😌

All these operators follow the usual precedence: unary operators ('!' and '~') get evaluated first, then conjunction '&', then disjunction '|'. Wanna override that? Use parenthesis '(' and ')' inside the condition. ✨

On top of all that logical stuff, conditions are based on atomic operators that compare the 'in place' file to the 'to be added' file. Here they are, bestie:

I — true only if the 'in place' entry is an inode. This one doesn't care at all about the to-be-added object. Note that ~I can check the nature of the 'to be added' object. A 'detruit' entry — which records that a file has been removed since the archive of reference — is not an inode, and it's the only type of entry that isn't an inode. So you can define an action on 'detruit' objects using "!I" for the 'in place' entry and "!~I" for the 'to be added' entry. 💀
D — true only if the 'in place' entry is a directory. To find out if the 'to be added' is a directory, you'd use that inversion operator: ~D. 🗂️
F — true only if the 'in place' entry is a plain file (also true if that plain file is a 'hard link' — that's it, if its inode is linked several times to the directory tree). 📄
H — true only if the 'in place' entry is an inode linked several times to the directory tree (= hard link). It could be a plain file, a Unix socket, a pipe, char device, a block device, for example. 🔗
A — same as H but the current 'in place' entry is the first link we meet pointing to that hard-linked inode. 🥇
R — true if the 'in place' entry is more recent than or of the same date as the 'to be added' entry. The last modification date [aka mtime] is used for this comparison. If the 'to be added' entry is not an inode (and thus has no mtime), the 'in place' is considered more recent. Same deal if the 'in place' entry isn't an inode (and has no mtime for comparison) — it's also assumed to be more recent. ⏰
R(<date>) — true if the 'in place' entry is more recent than or of the same date as the fixed <date> given in argument. No consideration is done toward the 'to be added' element. The <date> format is the same as the one used with the -af option. If an entry has no mtime (it's not an inode, for example), it's assumed to have a virtual mtime of zero. 📅
B — true only if both 'in place' and 'to be added' are plain files (hard-linked or not) and if the 'in place' file's data is larger or equal to the 'to be added' file's data. If one or both entries aren't plain files (or hard links to plain files) and the file size comparison isn't possible, the 'in place' entry is assumed to be 'bigger' than the 'to be added' entry. 📏
S — true only if the 'in place' data is saved in the archive (not marked as unchanged, nor marked as only inode metadata changed, since the archive of reference). Note that while extracting files from an archive, the 'in place' file is the one in the filesystem, which always has its data 'saved' (from libdar's point of view). The 'inversion' of this atomic operator, ~S, may still be interesting in the context of restoration. 💾
Y — true only if the 'in place' data is saved but dirty (a plain file having its data changed at the time it was read for backup). Note that restoring in sequential read mode, it is not possible to know whether a file is dirty (it is possible to know once having read its data, but sequential reading does not allow then to skip forward to get the dirty state of the file and skip backward to eventually restore that file, depending on the overwriting policy result). 😭
X — true only if the 'in place' data is a sparse file. 🕳️
T — true only if the 'in place' and 'to be added' entries are of the same type (plain file, Unix socket, named pipe, block device, char device, symlink, directory, 'detruit' (which stands for file deleted since the archive of reference was done), and so on). Note that the number of links to the inode (i.e., whether this is a hard link or not) is not taken into account. 👯
L — true only if the 'in place' entry has a delta signature associated with it. ✍️
P — true only if the 'in place' entry is a binary patch. 🩹
E — true only if 'in place' and 'to be added' are of the same type and have the same inode data information: uid, gid, permission, modification date are taken into account; atime and ctime are ignored in this comparison. If both are plain files, the file sizes must be the same for this condition to succeed. For char and block devices, both major and minor numbers must match. Last, for symlink, the target (the file path they point to) must be the same. 🪪
e — true if the 'in place' entry has EA (may they be saved or just recorded as existing). 🧾
r — true if the 'in place' entry has more recent or equal dated EA to the 'to be added' entry. If 'to be added' has no EA or is even not an inode, true is returned. If 'in place' has no EA or is even not an inode, true is returned unless 'to be added' has some EA. The comparison is done on ctime dates. ⏳
r(<date>) — true if the 'in place' entry has more recent or equal dated EA to the fixed <date> given in argument. No consideration is done toward the 'to be added' element. The <date> format is the same as the one used with the -af option. If an entry has no date (ctime date) (when it is not an inode, for example), it is assumed to have a virtual ctime of value zero. 📆
m — true only if 'in place' has more or equal number of EA entries in its set of EA than 'to be added' has. If an entry has no EA or is not even an inode, it is assumed it has zero entries. The comparison is done on this number. Note that the number of EA entries is not the size used to store these entries. For example, the EA entry "user.test" counts for 1, whatever is the length of the value associated to it. 🔢
b — true when the 'in place' entry's EA set is bigger than, or the same size as, the 'to be added' entry's EA set. If an entry has no EA at all, or isn't even an inode, bestie, we just assume it's rocking a zero byte length EA set, and the comparison happens on that number instead. Heads up though: the comparison is done on the bytes used to store the whole EA set attached to a given file.
s — true when the 'in place' entry is an inode (or a hard linked inode) and has its EA saved in the archive of reference — not just marked present, but genuinely unchanged since last backup. This test does not take the 'to be added' entry into account. Periodt.

Okay so the pattern? Uppercase letters get kept when the comparison is based on the inode or the data, while lowercase letters are for atomics based on EA. Iconic little convention, honestly. Now that we've completed our tour of this feature, let's see some examples:

-/ Pp As we already saw, this is literally what the -n option does for files when no overwriting policy is defined — it avoids any overwriting for Data as well as for EA. No notes.
-/ "{!T}[Pp] {R}[{r}[Pp]Po] {r}[Op] Oo" Spaces and tabs are allowed here just to make it readable, slay. This policy says: if the files in conflict are not of the same type, then keep the Data and EA of the entry 'in place'. Else if 'in place' has the more recent data, then if 'in place' has the more recent EA, keep both its Data and EA; otherwise keep only its Data and overwrite its EA. Else (so, if 'in place' does not have the more recent data), if it has the more recent EA then overwrite the data but keep its EA, otherwise overwrite both its data and EA. This policy is lowkey obsessed with preserving the most recent data or EA, but it does not take into account the fact that EA or Data is effectively saved into the archive, or just marked as unchanged since the archive of reference. 🙈
-/ "{!T}[{~D}[Oo] Pp]" If entries are not of the same type, and if the 'to be added' entry is a directory, then we keep it and overwrite the 'in place' entry; otherwise we keep the 'in place' entry. If the entries are of the same type, the policy provides no action at all, so the default action gets used: "Pp". And you can swap that default action out super easily with a chain operator:
-/ "{!T}[{~D}[Oo] Pp] ; Aa" In this case, instead, if the entries are of the same type, the user will be asked what to do. Main character energy: you decide. 💅
-/ "{!T|!I}[{R}[Pp] Oo] {I&~I}[{S}[{~S}[{R}[P*] O*] P*] {~S}[O*] {R}[P*] O* ; {s}[{~s}[{r}[*p] *o] *p] {~s}[*o] ] {r}[*p] *o" Okay this one looks like it's giving a lot, but just read it as an illustration of what's possible: if both 'in place' and 'to be added' are not of the same type, we keep the data and EA of the most recent file (by last modification date). Else, both are of the same type. If both are inode, we evaluate a two-expression chain (expressions get separated by a semicolon ';') that we'll look at in detail further on. Else, if they're of the same type but not inode, we take the EA and data of the most recent entry (that's the last 10 chars of the string). Now, the inode case: the first expression in the chain sets the action for data and leaves the action for EA undefined, while the second one is the exact equivalent but instead leaves the action for data undefined '*' and sets the action for EA. Both expressions follow the same principle: if both entries are saved in the archives (as opposed to just marked as unchanged since the archive of reference), the most recent EA/Data is kept; else, the one of the inode that is saved is kept; but if none is saved in the archive, the most recent entry (mtime/ctime) is kept. 🧚

-^, --slice-mode perm[:user[:group]] — sets the permission and ownership to use for created slices. By default, dar creates slices with read and write available for anyone, letting the umask variable disable some privileges according to the user's preferences. If you need something more restricted, hand over the permission as an octal value (so it begins with a zero), like 0600 to only grant read and write access to the user. Be careful not to accidentally stop dar from writing to its own slices — like, if you provide a permission such as 0400, that's on you bestie. Also note the umask is always applied, so specifying -^ 0777 will not grant world wide read-write access unless your umask is 0000. 💀
-_, --retry-on-change count[:max-byte] — when a file has changed at the time it was read for backup, you can ask dar to retry saving it again. By default a file can be re-saved up to 3 times (that's the 'count' field), and you can set it to zero to disable this feature entirely. Optionally, the overall maximum amount of byte allowed to be wasted due to retrying a changing file's backup can be given after a colon character (:), that's the 'max-byte' field. By default (so, when no --retry-on-change option is specified) a limit of 1 wasted byte is allowed, which is the mininum. Specifying zero for max-byte sets no limit on the amount of wasted bytes (same as if no 'max-byte' was specified), and each changing file is then saved up to 'count' times if necessary.

A file is considered as changed when the last modification time has changed between the time the file was opened for backup and the time it was completely read. In some situations it is not possible to replace the already saved data for a file (writing the archive to a pipe, for example), and in that situation only, a second copy of the file is added just after the first previous try — which leads that previous try to become inaccessible, though it still holds some place in the archive, where from the designation of "wasted bytes". You can remove all wasted bytes from an archive using the merging/filtering feature: dar -+ new_arch -A old_arch -ak.

Note: since release 2.5.0, in normal condition no byte is wasted when a file changed at the time it was read for backup, except when doing a backup to pipe (using the '-c -' option), except if the beginning of the modified file is located in a previous slice, and except if slice hashing or strong encryption is used.

-ad, --alter=decremental — this flag is to be used only when merging two archives. Instead of the usual merging where each file of both archives is added to the resulting archive with eventually a tie using the overwriting policy (see the -/ option), here the merging builds an archive which corresponds to the decremental backup done based on two full backups. The -A backup is expected to receive the older archive, while the -@ is expected to point to the more recent one. If this option is used, the eventual overwriting policy is ignored and replaced internally by -/ "{E&R&~R&(A|!H)}[S*] P* ; {(e&~e&r&~r)|(!e&!~e)}[*s] *p". Additionally, files found in the newer archive that did not exist in the older are replaced by a 'detruit' entry, which marks them to be removed at restoration time. For more information about decremental backups, read the usage_notes.html file in the documentation. And ngl, note that decremental backup is not compatible with delta binary. ✨
-asecu, --alter=secu — okay bestie, this one turns OFF the ctime check that dar does by default during a differential backup 💅

So here's the tea: if the ctime of a plain file has changed since the archive of reference was done, while every other value stays unchanged (inode type, ownership, permission, last modification date), dar throws a "SECURITY WARNING" at you, because that could be the sign of a rootkit lurking 👀

You should reach for -asecu to disable this type of warning globally if you're doing a differential backup of just-restored data (aka a differential backup with the archive used for restoration taken as reference).
Why? Because in that exact situation, since it is not possible to restore ctime, the restored data's ctime will have changed while other parameters stay unchanged for all restored files, which makes dar scream a warning for literally every restored file 😭
This security check is also disabled (implicitly) if dar is run with -ac.
And last thing: if a file has only its EA changed since the archive of reference was done (new EA, removed EA, modified EA), the security warning will show up anyway — that's a false positive btw 🫠

-., --user-comment "<message>" — this one lets you drop an arbitrary message into the archive header, like a lil signature on your work ✨

Warning! this message is always stored in clear text, even if the archive is encrypted. No cap. 🙈

You can see the message you inserted in an archive by displaying the archive summary (dar -l <archive> -q) 🎀

Some macros can be used inside the <message>:

%c — is replaced by the command line used. Note that for security, any option related to archive encryption is removed (-K, -J, -$, -#, -*, -%). The command included from a DCF file (see -B option) are never added by this macro. As a consequence, if you do not want to see --user-comment stored in user comments you can add the --user-comment definition in an included file like ~/.darrc for example. 🧚
%d — this is the current date and time ⏰
%u — this is the uid under which dar has been run
%g — this is the gid under which dar has been run
%h — the hostname on which the archive has been created 🖥️
%% — the % character.

-3, --hash <algo> — with this option set, when creating, isolating, merging or repairing an archive, beside each generated slices an on-fly hash file of the slice is created using the specified algorithm 🔥

Available algorithm are "md5", "sha1", "sha512" and "whirlpool". By default no hash file is generated.

The hash file generated is named based on the name of the slice with the .md5, .sha1, .sha512 or .whirlpool extension added to it at the end. These hash files can be processed by md5sum, sha1sum, sha512sum and rhash (for whirlpool algorithm) usual commands (md5sum -c <hash file>) to verify that the slice has not been corrupted 👑

Note that the result is different than generating the hash file using md5sum or sha1sum once the slice is created, in particular if the media is faulty: calling md5sum or sha1sum on the written slice will make you compute the hash result on a possibly already corrupted file, thus the corruption will not be seen when testing the file against the hash at a later time. 💀

Note also that the creation of a hash file is not available when producing the archive on a pipe ("dar -c -").

-7, --sign email[,email[,...email]] — when creating, isolating, merging or repairing an archive with public key encryption (read -K option) it is also possible to sign it with one or more of your private key(s) 💜

At the difference of the hash feature above, only the randomly generated key used to cipher the archive — key that is dropped at the beginning and at the end of the archive — is signed. If the archive is modified at some place, that part will not be possible to decipher, but signature verification will stay quick and valid, unless the part that has been tempered is the key inside the archive, in which case signature check will report a failure and archive will not be readable at all 😱

If the signature is valid and the archive could be extracted without error, the whole archive could be assumed to be signed by the gnupg key owners, but read below the security note. See also GNUPGHOME in the ENVIRONMENT section at the end of this document.

A summary information about the signature information is displayed while listing an archive in summary mode "dar -l <archive> -q". For any operation involving a signed archive, a short message only shows if the archive is signed an one or more signature check failed, no message is displayed in case of successful signature check. This warning may be disabled using the --alter=blind-to-signatures command. 🌸

-<, --backup-hook-include <mask> — the mask is applied to path+filename during backup operation only. If a given file matches the mask, a user command (see -= option below) will be run just before proceeding to the backup of that file and a second time right after it has completed. See also -> option below. 🦋

IMPORTANT: if using the short option, you need to enclose it between quotes: '-<' for the shell not to interpret the < as a redirection. 🫶

This option can be used several times on command-line.

->, --backup-hook-exclude <mask> — the mask is applied to path+filename during backup operation only. If a given file matches the mask, even if it matches a mask given after -< option, no user command will be executed before and after its backup. 🙅

The -< and -> options act like -g and -P options (but for a different purpose), they can receive wildcard expression and thus have their comportment driven by the --alter=globe and --alter=regex expressions seen above, as well as the --alter=mask option. Last the --alter=case and --alter=no-case modify also the way case sensitivity is considered for these masks. By default, no -> or -< option, no file get selected for backup hook. ✨

IMPORTANT: if using the short option, you need to enclose it between quotes: '->' for the shell not to interpret the > as a redirection. 😭

This option can be used several times on command-line.

-=, --backup-hook-execute <string> — for files covered by the mask provided thanks to the -< and -> options, the given string is executed just before the backup of that file starts and right after it has completed. 🎀

Pay attention: when the action applies to a directory, it does not apply to any file and subdirectory located inside this directory. 👀

Several macros can be used that are substituted at run time:

%% — will be replaced by a literal %
%p — will be replaced by the full path under backup
%f — will be replaced by the filename (without the path)
%u — will be replaced by the UID of the file
%g — will be replaced by the GID of the file
%t — will be replaced by a letter corresponding to the type of inode: 'f' for plain file, 'l' for symlink, 'd' for directory, 'c' for char devices, 'b' for block devices, 's' for sockets, 'p' for pipes, 'o' for doors. 🚪
%c — and most interesting, %c (c for context), will be replaced by "start" or by "end" when the command is executed before or after the backup respectively. 👑

For example, this feature let one dump a database just before its backup starts, and remove the dumped file(s) once the backup of that part has completed. 💅

✨ Note ✨ when a directory gets picked for this feature, the user command runs before dar starts backing up any file sitting in that directory and its subdirectories, with the context "start" (peep %c above 👀). And yeah, it also runs, like you'd expect, after all the files in that directory and subdirectories have been saved — this time with context "end". But here's the tea 🫖: between those two executions, even if a file does match the backup-hook masks (so it lives inside that directory), no command will be executed for it! The assumption is that once a directory has asked for a backup-hook to be executed, that hook (or user command) is handling/prepping all the data in that directory. periodt.

Because of performance reasons — creating a shell process to interpret the user command-line plus actually running the user command itself (and that's once before and once after a file to backup) — it's not advised to use this feature for a large number of files under backup (or worse, 💀 all of them). The whole point of this feature is to prep the backup of some particular structures that need coherence between files to be saved properly. If all the data under backup is wrapped up in such a coherent structure, better to act before and after running the dar command itself (like stopping/suspending and restarting/resuming the concerned service/process). And if lots of these structures are under backup or nested inside each other, saving them independently (eventually using this backup-hook feature for some or all of them) and merging the resulting dar backups afterward, or feeding a dar_manager database with them, are also options to consider. 💅

The environment variable DAR_DUC_PATH also applies to these user commands (check -E above, or the ENVIRONMENT paragraph below). 🦋

-ai, --alter=ignore-unknown-inode-type — so when dar bumps into an inode type it doesn't know about (back in the day, that was the case for Door inodes on Solaris, but dar handles Door inodes since release 2.4.0), it throws a warning about not being able to handle that inode. And this warning pops up even if that entry is filtered out via the -X, -I, -P, -g, -[ or -] options — as soon as some other entry in that same directory has to be considered for backup, which makes dar read that directory's contents and fail on that unknown inode type (filtering happens based on the result of the directory listing). This option exists so dar doesn't throw that warning in that situation. 😌
-8, --delta sig — this one works for archive backup, isolation and merging. ⚠️ Important: read also the best practice paragraph below!

When it's called during a backup operation, it makes dar create a delta signature for each file: if the file is new or has changed, a signature gets computed and stored beside the file's data, which increases the archive size. If the file isn't new and hasn't changed (differential backup context) and a delta signature is found in the archive of reference (or isolated catalogue), that signature gets copied to the resulting archive, but not the file's data. If the reference archive doesn't hold a delta signature, a new delta signature gets computed based on the current data found on the filesystem for that file and then stored in the resulting archive. But in any case, without --delta sig the resulting archive will hold no delta signature. 📝 Note that delta signature transfer is not possible when the archive of reference is read in sequential mode (still here for backup operation), so delta signature is disabled when the archive of reference is read in sequential mode.

For isolation and merging operations, the behavior is a lil different: --delta sig lets dar transfer existing delta signatures from the original archive to the isolated/merged one, but it does not make dar compute delta signatures for files that don't have one — unless one of the --include-delta-sig or --exclude-delta-sig options is specified; in that case the delta signatures are transferred/dropped, and if not present they're calculated according to those mask options. But heads up 🙈: it's not possible to calculate a delta signature for unsaved files in the archive of reference (because the archive of reference doesn't hold their data), nor for fully saved files when merging is performed keeping files compressed (see the -ak option). Another restriction while merging concerns sparse files: it's not possible to calculate a binary signature for files stored as sparse files, but if the sparse file detection mechanism is activated at merging time, a delta signature can be calculated for sparse files too even if it's missing in the reference archive. In short: if you want recalculation of delta signature while merging, don't keep the file compressed (don't use -ak), and if you want to avoid having sparse files excluded from the delta signature recalculation, activate sparse file detection (use -ah). And delta signature transfer is not possible for on-fly isolation — you need to do normal archive isolation to get an isolated catalogue with delta signatures. 💀

-8, --delta sig:<function>:<multiplier>[:<divisor>[:<min>[:<max>]]] — this variant of --delta sig lets you specify the block length used to build delta signatures. Bigger values reduce the CPU load needed to build the delta signature, but they also lead to less accuracy when computing the delta binary, which means a larger delta patch and more data saved when a file has changed. The block len is calculated following this formula:

block_len = function(filesize)*multiplier/divisor

If this calculated value is lower than "min", it gets set to min. If the calculated value is greater than "max", it gets set to max — unless max is set to zero, in which case the value is kept as is. And of course "divisor" cannot be null. 🚫 The available functions are:

fixed — always returns 1. In other terms, the block size is independent from the file size to build the delta signature for.
linear — returns the filesize. here, you will most of the time use 1 for multiplier and increase divisor to at least 10 for it makes sense.
log2 — returns the upper rounded power of 2 closest to the file size (base 2 logarithm).
root2 — returns the approximated value of the square root of the file size. Note that for better performance and as accuracy is not important here, this function is implemented as exp2(log2(filesize)/2) where exp2 and log2 are based on the integer left and right bit shift operations.
root3 — returns the approximated value of the cube root of filesize, implemented as exp2(log2(filesize)/3)

All numerical fields can receive a multiplier suffix (k, M, ...) — for more details about these suffixes, see the -s option description. If not specified, "max" defaults to zero (no maximum value defined). If not specified, "min" defaults to RS_DEFAULT_BLOCK_LEN (see below for details on this symbol). If not specified, "divisor" defaults to 1. Using "--delta sig" without additional fields is equivalent to using --delta sig:fixed:RS_DEFAULT_BLOCK_LEN up to dar/libdar version 2.7.10. Starting release 2.7.11, the default is equivalent to use --delta sig:root2:1:1:RS_DEFAULT_BLOCK_LEN:64*DEFAULT_BLOCK_LEN, which is almost what is used by the rsync command line tool (rsync uses rather 700 bytes as minimum block size), where "RS_DEFAULT_BLOCK_LEN" is taken from librsync and is today equal to 2048 bytes (which may well change in the future by the way if librsync maintainers decide to do so 👑).

-{, --include-delta-sig <mask> — okay so bestie, listen 💖 by default, the second you hand over --delta sig, delta signatures get computed for every single file enrolled in the backup operation (peep --delta-sig-min-size too, she's relevant). This option and her sister --exclude-delta-sig are the ones that let you narrow it down to only the files you actually want signatures calculated for in that situation. The mask applies to the whole path, the exact same way the -P/-g options do. iykyk.

Now for merging or isolation operations 🦋 — when --delta sig is used there, no delta signature gets computed, only the existing ones get transferred as-is, no restriction, periodt. Wanna change that vibe and either drop or add a delta signature to files that didn't have one in the archive of reference? Then you specify a combo of --include-delta-sig or --exclude-delta-sig together with --delta sig. This option, plus --exclude-delta-sig, can be used several times on the command-line but honestly they're useless/ignored without --delta sig. Also go look at -am, -ag and -ar options, they're part of this whole situation 💅

-}, --exclude-delta-sig <mask> — files matching the given mask will never have their delta signatures calculated, --delta sig option specified or not, doesn't matter, no cap 🙈 See also the --include-delta-sig option right above and --delta-sig-min-size right below.
-6, --delta-sig-min-size <number> — for archive merging, isolation and creation, when dar has to (re-)calculate delta signatures, this option modifies the minimum file size (in bytes) below which dar never calculates delta signatures. It acts independently from --include-delta-sig and --exclude-delta-sig, however it cannot re-activate delta signature recalculation all by itself while merging/isolating an archive — it requires either --exclude-delta-sig or --include-delta-sig to be active in that situation. For archive backup instead? It doesn't need --exclude-delta-sig nor --include-delta-sig to act, it only needs --delta sig option to be set ✨ By default, this minimum size is 10 kio. The same option suffixes (k for kilo, M for mega, G for giga, T, ...) that are available with the --slice option can be used here too 🎀 Using zero as the argument gives the same result as not specifying this option at all (default size).
-8, --delta no-patch — in the context of differential backup, this option leads dar to never consider files for delta binary even if delta signatures are present, like, at all. By default, delta binary (rsync-like) operation is performed when a file has changed since the archive of reference was made and if a delta signature could be found in the archive of reference for that file (or in the isolated catalogue used as reference for the incremental/differential backup). If no delta signature could be found, or if --delta no-patch is used, the normal behavior happens instead, which consists of saving that whole file in the archive. Note that if the archive of reference is read in sequential mode, the --delta no patch is required — dar will refuse to execute the operation, because sequential read and binary delta are not compatible. Why? Because reading an archive in sequential mode doesn't let you skip backward to fetch the delta signature necessary to set up a delta patch. and that's just the rules 🌸

⚠️ bestie. pay attention here. sequential read + binary delta = dar says no.

✨ Binary delta options usage and best practices ✨

First things first, we gotta understand that binary delta has advantages (less storage requirement, slay) and also drawbacks: data corruption has a wider impact on your ability to restore a given file, and restoration of an incrementally backed up file may ask for much more than one archive to be used 😭 To limit the impact of that first drawback, dar binary delta is done per file, not globally on the total amount of saved data. You are also strongly encouraged to protect your backups with parity data using par2 (see the dar_par.dcf file in the examples section of the documentation) 🫶 Adding par2 data will increase storage requirement by a little, but usually much less than the amount gained using binary delta.

Last drawback: binary delta relies on checksum (contained in the delta signature) and not on the real data to build the binary delta. There are chances that two different files provide the same checksum — even if those chances are very low, the probability is not null. The consequence is that using binary delta, the risk exists that the restored data does not match the original data, and this will not be noticed by the librsync library on which libdar relies for that feature 💀 Dar adds a second level of checksum, to detect data corruption inside the archive and to check that the file the delta patch is about to be applied is the expected base file — this reduces the risk of "collision" but does not remove it completely.

Okay after all those warnings, let's get into the best practices about binary delta 💅

Once a full backup has been done using --delta sig, any differential backup made based on this archive will use binary diff for files having a delta signature present in the full backup. If you always make differential (not incremental) backups based on such a full backup, you have nothing more specific to do in regard to binary delta — dar will handle it transparently, iconic behavior honestly. In particular, you do not need to invoke --delta sig at subsequent backup, and this saves space in differential archives as well as CPU cycles ✨

However 🌸 when doing incremental (not differential) backups this time, if you want dar using binary delta at each subsequent incremental backup, delta signatures must be present in the successive incremental backups. This is done by using --delta sig option for each new incremental backup created.

If you were used to use isolated catalogues before release 2.6.0, you can add --delta sig option while isolating a catalogue from an archive containing delta signatures. Such an isolated catalogue will be much larger than what it can be without this option, but it can be used as reference for a new differential/incremental backup, letting dar rely on binary delta 🦋 Isolated catalogues generated without --delta sig do not contain delta signature and cannot lead to binary delta operation when used as reference for an incremental or decremental backup.

Another way of doing differential backup is to make a normal full backup without --delta sig option, and only add delta signatures at archive isolation time using --delta sig --include-delta-sig "*" options. Binary delta signature will then be calculated based on the saved files. Then, using the resulting isolated catalogue as reference, dar will be able to proceed to binary delta for the differential backup. If this works pretty well for differential backup (or the first incremental backup) which is based on a full backup, for incremental backup this is less adapted — because a file that has not changed since the archive of reference was made does not hold any data, and calculating the delta signature is not possible. The first method explained two paragraphs above is better, since the incremental backup fetches the already calculated delta signature from the reference to keep it in the resulting incremental backup, so even without data, binary delta is still possible 👑

Isolated catalogue using the --delta sig option can still be used as backup of the internal catalogue they have been isolated from. However, as they hold their own delta signatures, such an isolated catalogue can only have access to its own ones, not to those of the archive of reference. In particular, when testing an archive (-t option), using -A option to rescue the archive internal catalogue using an isolated catalogue containing delta signatures, dar will not be able to check that there is no corruption in the delta signatures fields of the archive under test. For that type of testing, either use the internal catalogue of the archive, or rescue it using an isolated catalogue built without --delta sig option 🙈

-az, --alter=zeroing-negative-dates — dar/libdar saves dates as a number of seconds since the beginning of year 1970, the well-known "Unix time" (plus a positive fraction for sub-second time-stamping) ⭐ Some systems may return a negative number as the Unix time of a given file (files having dates before 1970). In that situation, by default and since release 2.5.12, dar pauses and asks the user whether to assume the date as being zero 😭 But with the -az option, dar/libdar automatically assumes such negative dates to be zero and just issues a warning about the problem met. so much smoother, no cap 💖
-\, --ignored-as-symlink <absolute path>[:<absolute path>[:...]] — bestie, this one's about ✨vibes of symlinks✨. Whenever dar bumps into an inode that's part of the colon-separated list you handed over: if that inode isn't a symlink, this option does literally nothing, no effect, dead. But if it is a symlink, dar saves the file the symlink points at instead of the symlink itself (which is what dar does by default). Lowkey the juicy part: if the pointed-to inode is a directory, dar recurses into that directory. 🌀 You can also pass this whole list as the argument to the DAR_IGNORED_AS_SYMLINK environment variable instead of using --ignored-as-symlink (and heads up — the option takes precedence over the environment variable, so it wins the vibe check).
-', --modified-data-detection=any-inode-change, --modified-data-detection=mtime-and-size — okay so history lesson time 🫶. Before release 2.6.0, during a differential/incremental backup, if any part of a file's inode metadata changed (ownership, permission, ...) — even if the mtime (last modification time) and the file size stayed exactly the same — dar had no choice but to resave the whole file just to record those metadata changes. It's giving wasteful 😭: a total waste of backup time and space if, for example, only the ownership had actually been modified. You can still keep this historical behavior by invoking --modified-data-detection=any-inode-change. Since release 2.6.0, a new entry status ("inode-only") has been added, so dar can now re-save only the metadata when the inode change doesn't concern the data. To know whether the data changed or not, by default (i.e. when you give no --modified-data-detection option at all) dar looks at mtime and at the file's size only. Specifying --modified-data-detection=mtime-and-size (which is the default behavior) can be used to revert the action of --modified-data-detection=any-inode-change, for example when playing with included files (DCF files): the latest met takes precedence. 👑
-T, --kdf-param <integer>[:<hash algo>] — now THIS one is iconic and also slightly chaotic, stay with me 💅. Different from the listing context (see below), in the context of archive creation, merging, isolation and repair, the -T option lets you define the iteration count used to derive the archive key from the passphrase you provided (that's the archive encryption context) plus the hash algorithm used for that derivation. BUT — plot twist — -T has another, older meaning when doing archive listing. And because there was a lack of free characters to create a brand new CLI option, there was literally no other choice than recycling an existing option that isn't used in the context of archive creation/merging/isolation. 🫠 The consequence? The -T option must appear after the -+/-c/-C/-y options, so the operational context is known at the time the -T option is met and its --kdf-param meaning gets taken into account. And since --kdf-param is an alias to -T, this long form of the option must also be found after the use of either -c, -C or -+. Order matters, bestie, no cap.

Without --kdf-param the KDF function uses 200,000 iterations for md5, sha1 and sha512 (PBKDF2 from PKCS#5 v2) but only 10,000 for argon2. If libargon2 is present, that's the default hash algorithm; otherwise sha1 is used with PBKDF2. Valid parameters are "sha1", "sha512", "md5" and "argon2" for the hash algorithms, and a value greater than 1 for the iteration count. However, it's advised to use a value equal or greater to the default values mentioned previously. ✨ The suffixes described for the -s option are also available here (k, M, G, T, P, ...), however pay attention to the -aSI/-abinary mode, which defaults to binary — in which case -T 1k is equivalent to -T 1024. Example of use: --kdf-param 20k:argon2 🌸

-anru, --alter=never-resave-uncompressed — at creation time, or when re-compressing data at merging time (thus when option -ak is not used), dar by default tries to re-save a file uncompressed if the compression result takes more space than the uncompressed original data. Cute in theory! The drawback is that it leads dar to skip back the archive that's about to be created (the advantage is that it doesn't waste storage space, so it's a trade). This option lets you disable that feature: dar will then not skip back and will keep files compressed even if their compressed data takes more space than what they'd take uncompressed. 🔥
-arep, --alter=repair — for isolation operation only, this option makes dar able to isolate a catalog from a truncated backup. 🩹 This option transparently implies --sequential-read and --alter=force-first-slice, so it can read the content of the truncated archive. The isolated catalog can then be used to read the archive in direct mode for better efficiency (see the -A option used with -x/-l/-t commands), which avoids repairing — and that saves time (and non-rewritable media!) if the volume of data is huge. 🫶

🎀 RESTORATION SPECIFIC OPTIONS (to use with `-x`) 🎀

-k[{ignored|only}], --deleted[={ignore|only}] — okay so without an argument, or with the "ignore" argument, this option leads dar at restoration time to not delete files that have been deleted since the backup of reference (file overwriting can still occur though, don't be fooled 👀). By default, files that have been destroyed since the backup of reference are deleted during restoration, but a warning is issued before proceeding — except if -w is used. If -n is used, no file will be deleted (nor overwritten), so -k is useless when you're using -n. If the -/ option is used, this option without argument is ignored! With the "only" argument, this option only considers files marked as to be removed in the archive to restore: no files are restored, but some files are removed. When -konly (or --deleted=only) is used, the -/ option is ignored (as opposed to the --deleted=ignore option, which is ignored when the -/ is used — yes that's a little devious, iykyk 💀). And of course --deleted=ignore and --deleted=only are mutually exclusive, because if both of them were available at the same time dar would do nothing at all. 🙈
-r, --recent — only restore files that are absent or more recent than those present in the filesystem. If the -/ option is used, this option is ignored! ⭐
-f, --flat — do not restore the directory structure. All files will be restored in the directory given to -R, and if two files of the same name have to be restored, the usual scheme for warning (-w option) and overwriting (-n option) is used. No rename scheme is planned actually. When this option is set, dar does not remove files that have been stored as deleted since the last backup. (And yes — -f implicitly implies -k.) 🦋
-ae, --alter=erase_ea — [DEPRECATED, use -/ instead] Drop all existing EA of files present in the filesystem that will have to be restored. This way, the restored files will have the exact set of EA they had at the time of the backup. If this option is not given, a file to restore will have its EA overwritten by those present in the backup, and if some extra EAs are present they'll remain untouched. See the Note concerning Extended Attributes (EA) above for a detailed explanation about this behavior. If the -/ option is used, this option is ignored! 💅
-D, --empty-dir — at restoration time, if -D is not specified (default), any file and directory is restored in regard to the filtering mechanism specified (see the -I, -X, -P, -g, -[ and -] options). But if the -D option is provided, the restoration skips directory trees that do not contain saved files. This avoids having a huge empty tree with just a few restored files, especially when restoring a differential archive in an empty place. 🌈 Note: this feature cannot work when --sequential-read is used, since it's not possible to know whether a directory contains or not some saved files at the time the directory inode is read from the archive in sequential reading mode.
-2, --dirty-behavior { ignore | no-warn } — at restoration time, if a file in the archive is flagged as "dirty" (meaning it had changed at the time it was saved), the user is asked for confirmation before restoring it. Specifying "ignore" will skip those dirty files, while "no-warn" will restore them without user confirmation. 🚨 This feature is incompatible with sequential reading mode — in this mode dar cannot know whether a file is dirty before having restored it. In consequences, in --sequential-read, once a file has been restored, if it's found to be dirty it will be removed unless dirty-behavior is set to "no-warn". 😭
-/, --overwriting-policy <policy> — bestie, this one is for archive restoration ✨ and it lets you define when and how file overwriting can even happen. The deets live up above in the description of this option, go peek 👀
-A, --ref [[<URL>]<path>]/<basename> — okay so you can use this with an isolated catalogue to rescue an archive that got a corruption in the catalogue part 😭💀. More details are in GENERAL OPTIONS above, no cap.
-au, --alter=unix-sockets — literally do not restore unix sockets. By default, saved unix sockets get recreated at restoration time, so this is you saying "not today" 🙅‍♀️
-ap, --alter=place — since version 2.7.1 libdar stores the filesystem root path (that's the -R option you gave) used when creating a backup, and that's known as the 'in-place' path 🎀. At restoration time, by default dar uses the -R option you provide, or if you didn't specify one it uses the current directory as the root directory for the restoration operation. Using -ap makes dar read the in-place path from the backup and restore the data using that path instead. So this option is exclusive with -R, and it may make dar report an error if the archive didn't store any in-place path (older archive format, or a backup that came from merging two backups with different in-place paths). Awkward but true 💅
-affs, --alter=force-first-slice — so this option's first purpose was at restoration time when you're using an isolated catalogue. In that context dar still needs to read the archive format from the backup to restore 🧚. In sequential read mode, this info is always fetched from the beginning of the archive, but in direct access mode it may be fetched by reading the end of the last slice (that's the default behavior) or by reading at the beginning of the first slice (that's when -affs is set). The whole objective? Avoid fetching the last slice when you're working with very large backups 🔥. You can define a first slice (see the -S option) of for example 1 kB while the other slices (the -s option) can be specified arbitrarily large. With the help of an isolated catalogue based on this archive plus that first (small) slice, reading some data from this large backup then only needs the few (big) slices where the data actually lives — not more, periodt ✨
-aefd, --alter=extract-from-database — in this mode of data restoration, the argument given to the -x option should point to a dar_manager database 🌸. This is almost equivalent to using dar_manager's -r option, with the difference that there's only one process and all the dar options given on the command line are available to each backup/archive referred in the database that'll be used for this restoration. Dar_manager was designed to restore a few files, then got extended to a directory tree, but passing the fileset scope to restore between processes is not that efficient ngl. With the -aefd option you get better performance to restore the whole dataset referred from a set of full, incremental and/or differential backups referred in a dar_manager database 🫶. See also the -af -A <date> option to limit the restoration to the status data had before a given date.

with -aefd restoration mode, it's possible to restore in the state at a given date by means of -af and -A options. By default, the most recent state available is restored for all entries. The file filtering mechanism can also be used to restore only certain files and directories, instead of all that were present at the latest or given date state 💖

😤 TESTING AND DIFFERENCE SPECIFIC OPTIONS (to use with `-t` or `-d`) 😤

-ado-not-compare-symlink-mtime, --alter=do-not-compare-symlink-mtime — with this option set, when comparing a symlink, no message shows when the symlink in the archive and the symlink on the filesystem differ only by their mtime 👑. See also the -O option.
-ap, --alter=place — this one is also available as described just above for restoration options, iykyk 💅
-az, --alter=zeroing-negative-dates — dar/libdar saves dates as a number of seconds since the beginning of year 1970, the well known "Unix time" (plus a positive fraction for sub-second time-stamping). Some systems may return a negative number as the Unix time of a given file (files having dates before 1970), and in that situation, by default and since release 2.5.12, dar pauses and asks the user whether to assume the date as being zero 😳. But with the -az option, dar/libdar automatically assumes such negative dates to be zero and just issues a warning about the problem met. Slay.

No other specific option, but all general options are available except for example -w which is useless, as testing and comparing only read data. The -A option is available as described in GENERAL OPTIONS to backup of internal catalogue of the archive (assuming you have a previously isolated catalogue available) 🎀

Doing a difference in sequential read mode is possible, but hard linked inodes can only be compared to the filesystem the first time they are met — next hard links to this same inode cannot obtain the corresponding data because skipping backward in sequential read mode is forbidden 💀. In that situation, the hard links are reported as skipped, meaning that data comparison could not be performed. Fr fr, that's just how it is.

-affs, --alter=force-first-slice — this option also applies to testing and difference operations (see details above) ✨

💖 LISTING OPTIONS (to use with `-l`) 💖

-T, --list-format=<normal | tree | xml | slicing> — by default, listing gives you a tar-like output (the 'normal' output). But bestie, you can also get a tree-like output, an XML structured output, or an output focusing on slice(s) where each file's data, EA and FSA is located 🦋. The option --tree-format is an alias to --list-format=tree (backward compatibility, we love a legacy queen 👑). Note that the files doc/dar-catalog-*.dtd define the format of the XML output listing (this file is also installed under $PREFIX/share/doc).

the -Tslicing option can also be used with isolated catalogue generated with dar 2.5.0 or above, since isolated catalogues now contain a copy of the slicing layout of the archive of reference ✨. However, if the archive of reference has been re-sliced (using dar_xform) after the isolated catalogue was built, the slicing information would not be correct 😭. For that corner case, you can use the -s and -S options with -Tslicing to specify what the new slice sizes of the archive of reference are. Last thing: -Tslicing and --sequential-read options are not compatible except for isolated catalogues.

-as, --alter=saved — list only saved files 💅
-alist-ea, --alter=list-ea — lists the Extended Attributes name for each file that has some 🌸
-ay, --alter=byte, --alter=bytes — by default the file size is displayed to occupy the shortest number of characters by using the largest unit possible (KiB, MiB, GiB, and so on). With this option instead, the size is displayed with maximum precision using the exact number of bytes used for each file 🔥
-I, -X, -P, -g, -[, -] — can be used to filter files to list based on their name or path 🧚
-aheader — displays the header (when --sequential-read is used) or the trailer of the archive and then stops. This archive header/trailer is always in clear text even when the archive is ciphered 👀. This option exists to let you access these fields without providing the encryption key, iconic behavior honestly.
-afdd, --alter=fully-detailed-dates — show the sub-second fraction value of dates, according to the time precision that was available in the system where the backup was created ⭐

From the general options it seems only -vm and -b stay useful here. Note that -vm displays an archive summary first, where a detail of information about the archive can be obtained 💜. If you want to display only this summary, use -q with the -l option.

🌈 displayed fields 🌈

the listing output has a whole alphabet soup of little codes, so let's decode them, because they're lowkey carrying so much info: 💅

[Data] — the possible values are [ ], [Saved], [InRef], [DIRTY], [Inode], or [Delta]. Here's the tea: [ ] means the data wasn't saved because there's no change since the backup of reference. [Saved] means the data was saved completely, so this archive can restore the file without any other help. [InRef] was used in archives made by dar version 2.3.x and before when isolating a catalogue from an archive, and it means the file was saved in the reference archive. [DIRTY] means data is saved (like [Saved]) but it changed at the time dar was reading it for backup, which could lead dar to store the file in a state it never actually had. [Inode] means only permission, ownership, and ctime data changed since the archive of reference was done, and that is recorded in the archive; the data did not change according to the --comparison-field set or not set. Last but not least, [Delta] means the file's data is saved as a binary delta (or delta patch), which is much shorter than the full data like with [Saved]. It also means you can only restore the file if it exists on the filesystem in the state it had when the archive of reference was done, so the patch can be applied. That's the case, for example, if you just restored this file from the archive of reference. ✨
[D] — possible values are [-], [ ], or [D]. [D] means the delta signature associated with this file is present in the archive. [ ] means the file has no associated delta signature, so binary diff won't be possible for it. [-] is used for non plain files inodes where delta signature is not applicable. 💅
[EA] — possible values are " " (empty string), [ ], [InRef], [Saved], or [Suppr]. It shows whether Extended Attributes are present and saved ([Saved]), present but not saved ([ ]) which means there's no change since backup of reference, no EA saved for this file (empty string), or some EA were present in the archive of reference but none is currently available ([Suppr]). [InRef] was used when isolating a catalogue (release 2.3.x and before) from an archive, and means the file was saved in the reference archive. 🦋
[FSA] — each character represents a FSA Family:
- "L" is the first character (L/l/-) representing the ext2/3/4 FSA family.
- "H" is the second character (H/h/-) representing the HFS+ FSA family.
- "-" the third character is reserved for future FSA family and is always a dash for now. Uppercase means the FSA set is saved; lowercase means the FSA is present in the archive of reference and has not changed since that time. Last, a dash (-) means no FSA of that family has been saved for that file. 👑
[compr] — possible values are [....%], [-----], [ ], or [worse]. It shows if the file has been compressed ([...%]) and the compression ratio reached "(uncompressed-compressed)/uncompressed". For example, [ 33%] means the compressed data uses only 66% of the space required to store uncompressed data (33% of space saved thanks to compression). It can also show if the file is stored without compression ([ ] see -m, -Y, and -Z options), or if the file is not subject to compression because it is not a saved regular file ([----]), or if the file takes more space compressed than its original size ([worse]) due to compression overhead. Note that a 1% compression ratio brings quite no data reduction, while obviously 98% is a very performant compression (compressed file takes only 2% of the size required by the uncompressed data). 🔥
[S] — possible values are [ ] or [X]. [X] only applies to saved plain files, and tells you the file is stored using a sparse file data structure: not all data is stored, and long sequences of zeros are skipped. This also means that at restoration time, if the filesystem supports it, holes will be restored. To store hole information, libdar uses an escape sequence (a special sequence of byte), but to avoid real data being considered as such an escape sequence, a special escape sequence is used when data looks like an escape sequence. So if a data contains such an escape sequence, it must be read as if it contains holes to be able to restore back the data in its original form. For that reason, in some rare circumstances (saving a dar archive inside a dar archive without compression or encryption, for example), a file without a hole may be marked [X] as if it had holes and will be longer by one byte for each data sequence looking like an escape sequence. 😭
permission — see ls man page. Note that a star (*) is prepended to the permission string if the corresponding inode is linked several times to the directory structure (hard link). ⭐
user — owner of the file.
group — group owner of the file.
size — size in byte of the file (if compression is enabled, the real size in the archive is "compression rate" time smaller). 🎀
date — the last modification date of the file. The last access time is also saved and restored, but not displayed. 🌸
filename — the name of the file.
Extended Attributes — when using the -alist-ea option, for hard linked inode, the filename is followed by an integer between braces: entries with the same number point to the same inode. 👑
Slice(s) — in -Tslice mode, each file is given the range of slices it is located in. If slice size is chosen particularly small, some slices may contain no file, EA, or FSA data but only tape marks or the internal catalogue, leading the aggregation of reported slices not to cover all available slices of the archive. 💅

✨ EXPLICIT OPTIONAL ARGUMENTS ✨

okay so real talk: if dar has not been compiled with GNU getopt, which is not present by default on some systems like FreeBSD, you may lack the optional arguments syntax. For example, -z will create a parse error on the command-line, or in -B configuration files. The solution is to explicitly give the argument. Here follows a list of explicit argument to use in place of optional ones: 🫶

-z must be replaced by -z 9
-w must be replaced by -w d or -w default
-H must be replaced by -H 1
-0 must be replaced by -0 ref
-5 must be replaced by -5 ""
-p must be replaced by -p 1
-v must be replaced by -v all
-k must be replaced by -k ignore
-5 must be replaced by -5 user.libdar_no_backup
-M must be replaced by -M I:/

important ! When using GNU getopt(), optional arguments are available by sticking the argument to the short option: "-z" for example is available as well as "-z9". But "-z 9" is wrong — it will be read as the "-z" option and "9" as a command line argument (not an argument to the -z option). In the other side, when using a non GNU getopt this time, "-z" becomes an option that always requires an argument, and thus "-z 9" is read as the "-z" option with "9" as argument, while "-z9" will be rejected as a unknown option, and "-z" alone will generate an error as no argument is provided. In consequences, you need a space between the option (like "-z") and its argument (like "9"), when dar does not rely on a GNU getopt() call, which also imply you to explicitly use arguments to options listed just above. 💀

📬 USAGE MADE OF STDIN/STDOUT/STDERR BY DAR 📬

Okay bestie, sit down, because this part is about plumbing and it's lowkey the most important vibe check in the whole page. 💅

Dar, like literally every Unix command-line tool ever, gets created by a shell with a standard input (stdin), a standard output (stdout) and a standard error (stderr) so it can talk to you. That's the setup. That's the stage.

On the other side, dar has a non-interactive output and an interactive output. What's the point of having two? The idea is to keep in-band messages — the normal little "here's what step we're on" messages that go to the non-interactive output — totally separate from out-of-band messages, the ones that can actually influence the whole process or give you diagnostics on what fate dar's current operation is heading toward. Those live on the interactive output, plus its associated input. Two lanes, no traffic jams. 🛣️

🌅 At startup

In the very early phase — like, before dar has even interpreted the argc/argv arguments it got handed by the shell (those options and commands you pass to dar) — both outputs are bounded to stderr. Why? Because dar might be set up to read an archive from stdin (that's the --sequential-read option, or dar being used together with dar_slave) or to spit an archive out on stdout (-c -, for example). You can't have your info messages stomping all over your archive data, no ma'am. 🙅

A very basic lookup gets performed on the argv arguments list, just checking for the presence of a -Q option. Right after that:

If no controlling terminal is found — and unless -Q was found earlier — a warning message gets sent to the non-interactive output (which is stderr at that point) and all questions will assume a negative answer. Not me getting ignored by my own backup tool 😭
Otherwise, a new file-descriptor is opened on that controlling terminal, and it's used to fetch your future answers when interaction is needed. This preserves stdin, which is very much the point. 🫶

⌨️ During command-line parsing

Once the command-line option parsing has completed, dar checks: is any archive or backup expected to be output on stdout? If there's no -i and -o option, and no -c -, -C - or -+ - configuration requested (for example), then the non-interactive output is changed from stderr to stdout. Otherwise it stays on stderr. That's it, that's the rule. ✨

🏃 Running phase

So during the archive or backup processing:

Any information message goes to the non-interactive output (either stderr or stdout, whichever we landed on above).
Questions to the user go to the interactive output — that is to say, on stderr.

And if a controlling terminal was found, your answer gets fetched from that terminal through the extra file-descriptor that was opened during the startup phase. stdin stays untouched, because it's either being used for dar_slave or sequential-read mode, or it's just not being used at all. Iconic resource management, honestly. 👑

💥 Exception phase

In case an exception (= an error) that dar couldn't handle succeeds in happening, both outputs are set back to stderr and the error message embedded in the exception is displayed before dar terminates. Dramatic exit, but a clean one. 💀

🚪 EXIT CODES 🚪

dar exits with the following code, and each one is a whole mood:

0 — Operation successful. Slay. ✅
1 — Syntax error on the command line or in a DCF included file.
2 — Error due to a hardware problem or a lack of memory. The machine is going through it, not you.
3 — Detection of a condition that should never happen, and which is considered a bug of the application. 🙈
4 — Code issued when the user has aborted the program by answering a question from dar. This also happens when dar is not run from a terminal (say, launched from crontab) and dar has a question for the user. In that case dar aborts the same way it would if you pressed the escape key at the question prompt.
5 — Returned when an error concerning the treated data has been detected. The details, because they matter:
- While saving: a file could not be opened or read.
- While restoring: a file could not be created or replaced.
- While comparing: a file in the archive does not match the one in the filesystem.
- While testing: a file is corrupted in the archive.
6 — An error occurred while executing a user command (given with the -E or -F option). Mainly because the creation of a new process wasn't possible (process table is full) or the user command returned an error code (exit status different from zero).
7 — An error occurred when calling a libdar routine. This means the caller (the dar program) did not respect the specification of the API — and yes, this can be considered a particular case of bug. 🐛
8 — The version of dar you're using is based on finite length integers (it was compiled with the option --enable-mode=...). This code is returned when an integer overflow occurred. Use the full version (based on the so-called "infinint" class) to avoid this error.
9 — This code indicates an unknown error. The exception caching code responsible for taking care of new exceptions has probably been forgotten and not updated… this is a minor bug you are welcome to report. 🫶
10 — You tried to use a feature that has been disabled at compilation time.
11 — Some saved files have changed while dar was reading them. This may lead the data saved for that file to not correspond to a valid state for this file. For example, if the beginning and the end of the file were modified at the same time (while dar was reading it), only the change at the end will be saved (the beginning has already been read) — the resulting state of the file, as recorded by dar, has never existed, and may cause problems for the application using it. This is known as a "dirty" file in the archive. 🧼➡️🫠

🚨 SIGNALS 🚨

If dar receives a signal (peep the kill(2) man page), it will take the default behaviour, which most of the time means abruptly aborting the program — with the exception of these guys:

SIGINT — Generated by the terminal when you hit CTRL-C (with the terminal's default settings). It can also be generated with the kill command.
SIGTERM — Generated by the system when changing run-level, in particular when doing a shutdown. It can also be generated with the kill command.
SIGHUP — Depending on the system, this signal may be sent before the SIGTERM signal at shutdown time. It can also be generated with the kill command.
SIGQUIT — Generated by the terminal when you hit CTRL-\ (with the terminal's default settings). It can also be generated with the kill command.
SIGUSR1 — This signal can be generated by the kill command.
SIGUSR2 — This signal can be generated by the kill command.

For those previous signals, two behaviours exist, and the difference is a big deal:

For SIGHUP, SIGINT, SIGQUIT, SIGTERM and SIGUSR1, a delayed termination is done: the backup or isolation operation is stopped, the catalogue is appended to the archive, and the archive is properly completed with the correct terminator string. This way the generated archive is usable, and can be used as a reference for a differential backup at a later time. Note that if an on-fly isolation had been asked, it will not be performed, and no user command will be launched even if dar has been configured for it (the -E option). For SIGUSR2 instead, a fast termination is done: in the case of backup or isolation, the archive is not completed at all — only memory and mutex are released properly.

For both types of termination, and for other operations than backup or isolation, dar's behaviour is the same:

For restoration: all opened directories are closed and permissions are set back to their original values (if they had to be changed for the restoration).
For listing, comparison and testing: the program aborts immediately.

One more thing, bestie: when using one of the previous signals, dar will return with the exit status 4, meaning the user aborted the operation. Note that answering "no" to a question from dar may also lead dar to exit this way. And last — if before the end of the program the same signal is received a second time, dar will abort immediately. No second chances, periodt. 💅

📁 FILES 📁

$HOME/.darrc and /etc/darrc, if present, are read for configuration options. They share the same syntax as the file given to the -B option. If $HOME/.darrc is not present — and only in that case — /etc/darrc is consulted. You can still launch /etc/darrc from .darrc using a statement like -B /etc/darrc. 🌸

None of these files need to be present, but if they are, they are parsed AFTER any option on the command line and AFTER included files from the command line (the files given to the -B option).

NOTE: if $HOME is not defined, $HOME/.darrc defaults to /.darrc (at the root of the filesystem). 🫠

Else you can see the conditional syntax below, and the -N option above, which leads dar to ignore the /etc/darrc and $HOME/.darrc files.

🎀 CONDITIONAL SYNTAX 🎀

okay bestie, so your config files (that's the -B option, plus $HOME/.darrc and /etc/darrc) usually just hold a lil simple list of command-line arguments — split across lines or not, and honestly they can be mixed with comments too (peep the -B option for the deets). But here's the gag: you can also use make-like targets to ask for a specific set of commands to kick in under certain conditions. iconic behavior honestly 💅

A condition is literally just a reserved word immediately followed by a colon :. And the word + colon must stand alone on its own line — spaces or tabs beside it are fine, but that's it. The conditions you can use are:

extract: — all the options listed after this condition get used if, previously on the command line or file, the -x command has been used
create: — all the options listed after this condition get used if, previously on the command line or file (that -B option, yk), the -c command has been used
list: (or listing:) — if the -l command has been used
test: — if the -t command has been used
diff: — if the -d command has been used
isolate: — if the -C command has been used
merge: — if the -+ command has been used
repair: — if the -y command has been used
reference: — if the -A option has been used (except when -A is used for the snapshot feature or in conjunction with -af)
auxiliary: — if the -@ option has been used
all: — in any case
default: — if no -c, -d, -x, -t, -C, -l or -+ option has been used at this point of the parsing

The condition stops when the next condition starts, or at End of File. And the commands you insert before any condition are equivalent to the ones inserted after the "all:" condition. Quick remark bestie: -c -d -x -t -C and -l are mutually exclusive — only one of them can be used while calling dar. no cap 🫶

Here's an example of the conditional syntax, look at her:

       create:
         # upon creation exclude the
         # following files from compression
       -Z "*.mp3" -Z "*.mpg"

       all:
       -b
       -p

       default:
       # this will get read if not
       # command has been set yet
       -V
       # thus by default dar shows its version

       all:
       -v
       # for any command we also ask to be verbose
       # this is added to the previous all: condition

Last point: you may have the same condition several times (like several all: for example). They will just be concatenated together. periodt ✨

🦋 USER TARGETS 🦋

User targets are arbitrary words you find on the command line that do not start by a dash (-). On most systems they should be placed after the command and the options. They're collected from the command-line first, then comes the parsing of the command and the optional arguments. Their whole thing is to extend the conditional syntax we just talked about, by having a set of options activated by the user just adding a single word on the command-line. Of course, user targets must not be equal to one of the reserved words of the conditional syntax (extract, create, ... all, default). A valid target is a word (so, no spaces) composed of lowercase or uppercase letters (case is sensitive, so watch it) with eventually digits, dashes - or underscores _ characters. 💖

Let's see an example of use:

first, a DCF file named example.dcf that will be given on the command line:

       # normal set of files considered for backup

       create:
         -R /
         -P proc
         -P sys
         -P mnt
         -D

       # if the "home" user target is applied on command line the
       following command get added

       home:
          -g home

       # if the "verbose" user target is used, we will have some more
       verbosity ...

       verbose:
         -v
         -vs

Then we could run dar in the following ways:

dar -c test -B example.dcf — in that case only the command in the "create:" section of example.dcf would be used.
dar -c test -B example.dcf verbose — here, over the "create:" target, the commands under the "verbose:" target (-v and -vs) would be also used.
dar -c test -B example.dcf verbose home — last we use two user targets "verbose:" and "home:" in addition to the "create:" target of the usual conditional syntax.

ngl this next bit is a trap people fall into, so read it twice 💀

Note that if the last option may receive an argument, the first user target that follows it will be assumed an argument to that option. To avoid this, either change the order of options on the command line so that the last option is one that never or always uses an argument (for example -b never has an argument while -s always has one). Or separate the options from the user targets by the -- word. And of course you can also use the explicit argument of the last option (see the EXPLICIT OPTIONAL ARGUMENT section, above). 👑

Second point: it is allowed to have user targets inside a DCF file. Note however that targets are collected in a first phase, which leads some part of the file to be hidden (because the corresponding conditional syntax or user target is not present). Then, the remaining part of the file is parsed and actions for each option found are taken. At that time, new user targets found are just recorded, but they do not modify the current DCF file layout — in particular, hidden parts of the file stay hidden even if the corresponding user target is read in this same file. The next DCF parsing (which may be triggered by a second -B option on the command line, or by a -B option inside the currently parsed DCF file) will thus be done with the additional targets found in that first DCF file. So in a way you may have user targets that activate other user targets, but they will be activated starting the next -B file. Here follows an example of two DCF files, first.dcf and second.dcf:

       # cat first.dcf
         target3:
           -K toto

         target1:
           target2
           -B second.dcf
           target3

         target2:
           #never reached
           -s 10k

       # cat second.dcf
         target2:
           -v
         target3:
           -b

In that example, target1 activates both target2 and target3, but at the time of the parsing of first.dcf, neither target2 nor target3 were yet activated — thus -K toto and -s 10k will never be given to dar (unless activated beside target1 before first.dcf gets parsed). However, when comes the time to parse second.dcf, target2 and target3 are activated, so both -v and -b will be passed to dar, even if target3 is located after -B second.dcf in the file first.dcf. the way that works is so sneaky but so smart 😭🌸

🌈 ENVIRONMENT 🌈

DAR_DCF_PATH — if set, dar looks for Dar Configuration File (DCF files, see the -B option) that don't have a fully qualified path in the directories listed in the DAR_DCF_PATH environment variable. This variable receives a colon (:) separated list of paths, and dar looks in each of them in turn, up to the first file found under the requested name.
DAR_DUC_PATH — if set, dar looks for Dar User Command (DUC files, see the -E, -F, -~, -= options) that don't have a fully qualified path in the directories listed in DAR_DUC_PATH. This variable receives a colon (:) separated list of paths, and dar looks in each of them in turn, up to the first file found under the requested name.
DAR_SFTP_KNOWNHOSTS_FILE — if set, dar will not use the $HOME/.ssh/known_hosts file to check sftp remote server authenticity, but the file given as the value for this environment variable instead.

🚨 not me warning you about this: setting this variable to an empty string completely disables host validation, which is not recommended!!!

DAR_SFTP_PUBLIC_KEYFILE — by default dar will fetch the public key file in $HOME/.ssh/id_rsa.pub. If you use the former id_dsa.pub or more recent key types, you need to set this environment variable to point to the appropriate filename.
DAR_SFTP_PRIVATE_KEYFILE — by default dar will fetch the public key file in $HOME/.ssh/id_rsa. If you use the former id_dsa.pub or more recent key types, you need to set this environment variable to point to the appropriate filename.
DAR_IGNORED_AS_SYMLINK — receives a colon separated list of absolute paths, which, if they are symlinks, are not saved as symlink but as the inode they point to. For more details see the --ignored-as-symlink option above.
GNUPGHOME — for asymmetric encryption and signature, the keyring used is $HOME/.gnupg by default. You can change this default by setting GNUPGHOME to the directory containing the keyring. For example, if you are running dar as root and want to use your unprivileged account keyring, use the following:

export GNUPGHOME=~myaccount/.gnupg

dar -K gnupg:...@...,...@... --sign:...@... etc.

DAR_SECURED_MEMORY_SIZE_BYTES — lets the user specify the amount of secured memory dar/libdar should allocate. The provided value must be an integer number defining the secured memory size in bytes. By default 262144 bytes are allocated. 🫶

👑 CAPABILITIES 👑

dar fully supports the cap_chown capability, but by design, dar only uses this capability to restore files at their original ownership. Dar will thus not use this capability to access files and directories the caller would normally not have access to. In other words, it should be ok to set the cap_chown capability to the dar executable (setcap cap_chown+p dar). Calling dar from a process having the cap_chown in the inheritable set would lead the system to grant this capability to the dar process, while other users would not be granted this capability and would not be able to modify ownership of files at restoration time. This can be used for the system account that has the role of restoring data upon user requests, without giving root privilege to this restoration process. main character energy for real 💅✨

🍓 EXAMPLES 🍓

You can find some more examples of use in the tutorial, mini-howto, sample scripts, and other related documentation. All of these are available in dar's source package, and are also installed beside dar in the <--prefix>/share/dar directory. This documentation is also available on-line at http://dar.linux.free.fr/doc/index.html 🌸

💜 SEE ALSO 💜

dar_xform(1), dar_slave(1), dar_manager(1), dar_cp(1), dar_split(1), TUTORIAL and NOTES included in the source package and also available at http://dar.linux.free.fr/doc/index.html 🦋

💀 KNOWN LIMITATIONS 💀

okay bestie, real talk time, here's the tea on what dar cannot do for you 🫶

it saves and restores atime, mtime, and birthtime like the queen it is 👑
but it cannot restore ctime (that's the last inode change, iykyk) 😭 — and honestly? it's not dar's fault. there literally does not seem to be a standard call to do that under UNIX. the OS said "no 💅" and dar said "understandable, have a great day"

and if you wanna stay up to date on every little limitation, the freshest list lives at:

http://dar.linux.free.fr/doc/Limitations.html

🐛 KNOWN BUGS 🐛

they're all chilling right here, come vibe check them:

https://github.com/Edrusb/DAR/issues

🌈 AUTHOR 🌈

the icon, the legend, the main character who made all of this happen:

http://dar.linux.free.fr/
Denis Corbin
France
Europe

ate and left no crumbs, fr fr 🎀✨

and that's the whole page, bestie!! this was the 3rd Berkeley Distribution release, dated August 19st, 2026, and you just finished reading DAR(1) — every single bit of it. no cap. you're officially a dar girlie now 💖 go forth and archive responsibly 🦋

📦 where this page comes from

fedora 43: dar 2.8.6-1.fc43 · GPL-2.0-or-later
fedora 44: dar 2.8.6-1.fc44 · GPL-2.0-or-later
nixpkgs unstable: dar 2.8.6
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms