KurlesHS/restic
1
0
Fork 0
forked from TrueCloudLab/restic
Code Pull requests Activity

doc: Improve docs for --files-from et al

Browse source
This commit is contained in:
Leo R. Lundgren 2021-03-06 17:31:56 +01:00
parent c2569ff923
commit 5861bb031c
1 changed files with 30 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
doc/040_backup.rst
View file

@ -315,42 +315,48 @@ Including Files
*************** ***************
The options ``--files-from``, ``--files-from-verbatim`` and ``--files-from-raw`` 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 allow you to give restic a file containing lists of file patterns or paths to
command line. This is useful when a lot of files have to be backed up that are be backed up. This is useful e.g. when you want to back up files from many
not in the same folder. 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 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 with a byte-order mark. Leading and trailing whitespace is removed from the
patterns. Empty lines and lines starting with a ``#`` are ignored. patterns. Empty lines and lines starting with a ``#`` are ignored and each
The patterns are expanded, when the file is read, by the Go function pattern is expanded when read, such that special characters in it are expanded
`filepath.Glob <https://golang.org/pkg/path/filepath/#Glob>`__. using the Go function `filepath.Glob <https://golang.org/pkg/path/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``, The argument passed to ``--files-from-verbatim`` must be the name of a text file
except that it contains literal filenames. It does expand patterns; filenames that contains one *path* per line, e.g. as generated by GNU ``find`` with the
are listed verbatim. Lines starting with a ``#`` are not ignored; leading and ``-print`` flag. Unlike ``--files-from``, ``--files-from-verbatim`` does not
trailing whitespace is not trimmed off. Empty lines are still allowed, so that expand any special characters in the list of paths, does not strip off any
files can be grouped. 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 The ``--files-from-raw`` option is a variant of ``--files-from-verbatim`` that
by a zero byte (the NUL character), so that it can even handle filenames that requires each line in the file to be terminated by an ASCII NUL character (the
contain newlines or are not encoded as UTF-8 (except on Windows, where the ``\0`` zero byte) instead of a newline, so that it can even handle file paths
listed filenames must still be encoded in UTF-8). 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. All three options interpret the argument ``-`` as standard input and will read
Its file format is the output format generated by GNU find's ``-print0`` option. 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 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 .. 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: You can then use restic to backup the filtered files: