Merge pull request #3321 from restic/doc-files-from

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

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 <https://golang.org/pkg/path/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 <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``,
-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: