diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 580611b76..85b73cecf 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -319,42 +319,48 @@ Including Files *************** The options ``--files-from``, ``--files-from-verbatim`` and ``--files-from-raw`` -allow you to list files that should be backed up in a file, rather than on the -command line. This is useful when a lot of files have to be backed up that are -not in the same folder. +allow you to give restic a file containing lists of file patterns or paths to +be backed up. This is useful e.g. when you want to back up files from many +different locations, or when you use some other software to generate the list +of files to back up. The argument passed to ``--files-from`` must be the name of a text file that -contains one pattern per line. The file must be encoded as UTF-8, or UTF-16 +contains one *pattern* per line. The file must be encoded as UTF-8, or UTF-16 with a byte-order mark. Leading and trailing whitespace is removed from the -patterns. Empty lines and lines starting with a ``#`` are ignored. -The patterns are expanded, when the file is read, by the Go function -`filepath.Glob `__. +patterns. Empty lines and lines starting with a ``#`` are ignored and each +pattern is expanded when read, such that special characters in it are expanded +using the Go function `filepath.Glob `__ +- please see its documentation for the syntax you can use in the patterns. -The option ``--files-from-verbatim`` has the same behavior as ``--files-from``, -except that it contains literal filenames. It does expand patterns; filenames -are listed verbatim. Lines starting with a ``#`` are not ignored; leading and -trailing whitespace is not trimmed off. Empty lines are still allowed, so that -files can be grouped. +The argument passed to ``--files-from-verbatim`` must be the name of a text file +that contains one *path* per line, e.g. as generated by GNU ``find`` with the +``-print`` flag. Unlike ``--files-from``, ``--files-from-verbatim`` does not +expand any special characters in the list of paths, does not strip off any +whitespace and does not ignore lines starting with a ``#``. This option simply +reads and uses each line as-is, although empty lines are still ignored. Use this +option when you want to backup a list of filenames containing the special +characters that would otherwise be expanded when using ``--files-from``. -``--files-from-raw`` is a third variant that requires filenames to be terminated -by a zero byte (the NUL character), so that it can even handle filenames that -contain newlines or are not encoded as UTF-8 (except on Windows, where the -listed filenames must still be encoded in UTF-8). +The ``--files-from-raw`` option is a variant of ``--files-from-verbatim`` that +requires each line in the file to be terminated by an ASCII NUL character (the +``\0`` zero byte) instead of a newline, so that it can even handle file paths +containing newlines in their name or are not encoded as UTF-8 (except on +Windows, where the listed filenames must still be encoded in UTF-8. This option +is the safest choice when generating the list of filenames from a script (e.g. +GNU ``find`` with the ``-print0`` flag). -This option is the safest choice when generating filename lists from a script. -Its file format is the output format generated by GNU find's ``-print0`` option. +All three options interpret the argument ``-`` as standard input and will read +the list of files/patterns from there instead of a text file. -All three arguments interpret the argument ``-`` as standard input. - -In all cases, paths may be absolute or relative to ``restic backup``'s -working directory. +In all cases, paths may be absolute or relative to ``restic backup``'s working +directory. For example, maybe you want to backup files which have a name that matches a -certain regular expression pattern (uses GNU find): +certain regular expression pattern (uses GNU ``find``): .. code-block:: console - $ find /tmp/somefiles -regex PATTERN -print0 > /tmp/files_to_backup + $ find /tmp/some_folder -regex PATTERN -print0 > /tmp/files_to_backup You can then use restic to backup the filtered files: