diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 18edea10f..58b933720 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -132,8 +132,8 @@ Now is a good time to run ``restic check`` to verify that all data is properly stored in the repository. You should run this command regularly to make sure the internal structure of the repository is free of errors. -Including and Excluding Files -***************************** +Excluding Files +*************** You can exclude folders and files by specifying exclude patterns, currently the exclude options are: @@ -144,7 +144,9 @@ the exclude options are: - ``--exclude-file`` Specified one or more times to exclude items listed in a given file - ``--exclude-if-present foo`` Specified one or more times to exclude a folder's content if it contains a file called ``foo``` (optionally having a given header, no wildcards for the file name supported) - Let's say we have a file called ``excludes.txt`` with the following content: +Please see ``restic help backup`` for more specific information about each exclude option. + +Let's say we have a file called ``excludes.txt`` with the following content: :: @@ -159,34 +161,31 @@ It can be used like this: $ restic -r /srv/restic-repo backup ~/work --exclude="*.c" --exclude-file=excludes.txt -This instruct restic to exclude files matching the following criteria: +This instructs restic to exclude files matching the following criteria: + * All files matching ``*.c`` (parameter ``--exclude``) * All files matching ``*.go`` (second line in ``excludes.txt``) * All files and sub-directories named ``bar`` which reside somewhere below a directory called ``foo`` (fourth line in ``excludes.txt``) - * All files matching ``*.c`` (parameter ``--exclude``) - -Please see ``restic help backup`` for more specific information about each exclude option. Patterns use `filepath.Glob `__ internally, see `filepath.Match `__ for syntax. Patterns are tested against the full path of a file/dir to be saved, -even if restic is passed a relative path to save. Environment-variables in -exclude-files are expanded with `os.ExpandEnv `__, -so `/home/$USER/foo` will be expanded to `/home/bob/foo` for the user `bob`. To -get a literal dollar sign, write `$$` to the file. +even if restic is passed a relative path to save. + +Environment-variables in exclude files are expanded with `os.ExpandEnv `__, +so ``/home/$USER/foo`` will be expanded to ``/home/bob/foo`` for the user ``bob``. +To get a literal dollar sign, write ``$$`` to the file. Patterns need to match on complete path components. For example, the pattern ``foo``: * matches ``/dir1/foo/dir2/file`` and ``/dir/foo`` * does not match ``/dir/foobar`` or ``barfoo`` -A trailing ``/`` is ignored, a leading ``/`` anchors the -pattern at the root directory. This means, ``/bin`` matches ``/bin/bash`` but -does not match ``/usr/bin/restic``. +A trailing ``/`` is ignored, a leading ``/`` anchors the pattern at the root directory. +This means, ``/bin`` matches ``/bin/bash`` but does not match ``/usr/bin/restic``. -Regular wildcards cannot be used to match over the -directory separator ``/``. For example: ``b*ash`` matches ``/bin/bash`` but does not match -``/bin/ash``. +Regular wildcards cannot be used to match over the directory separator ``/``. +For example: ``b*ash`` matches ``/bin/bash`` but does not match ``/bin/ash``. For this, the special wildcard ``**`` can be used to match arbitrary sub-directories: The pattern ``foo/**/bar`` matches: @@ -195,6 +194,23 @@ sub-directories: The pattern ``foo/**/bar`` matches: * ``/foo/bar/file`` * ``/tmp/foo/bar`` +Spaces in patterns listed in an exclude file can be specified verbatim. That is, +in order to exclude a file named ``foo bar star.txt``, put that just as it reads +on one line in the exclude file. Please note that beginning and trailing spaces +are trimmed - in order to match these, use e.g. a ``*`` at the beginning or end +of the filename. + +Spaces in patterns listed in the other exclude options (e.g. ``--exclude`` on the +command line) are specified in different ways depending on the operating system +and/or shell. Restic itself does not need any escaping, but your shell may need +some escaping in order to pass the name/pattern as a single argument to restic. + +On most Unixy shells, you can either quote or use backslashes. For example: + + * ``--exclude='foo bar star/foo.txt'`` + * ``--exclude="foo bar star/foo.txt"`` + * ``--exclude=foo\ bar\ star/foo.txt`` + By specifying the option ``--one-file-system`` you can instruct restic to only backup files from the file systems the initially specified files or directories reside on. For example, calling restic like this won't @@ -207,10 +223,13 @@ backup ``/sys`` or ``/dev`` on a Linux system: .. note:: ``--one-file-system`` is currently unsupported on Windows, and will cause the backup to immediately fail with an error. -By using the ``--files-from`` option you can read the files you want to -backup from one or more files. This is especially useful if a lot of files have -to be backed up that are not in the same folder or are maybe pre-filtered -by other software. +Including Files +*************** + +By using the ``--files-from`` option you can read the files you want to back +up from one or more files. This is especially useful if a lot of files have +to be backed up that are not in the same folder or are maybe pre-filtered by +other software. For example maybe you want to backup files which have a name that matches a certain pattern: @@ -232,7 +251,11 @@ args: $ restic -r /srv/restic-repo backup --files-from /tmp/files_to_backup /tmp/some_additional_file -Paths in the listing file can be absolute or relative. +Paths in the listing file can be absolute or relative. Please note that +patterns listed in a ``--files-from`` file are treated the same way as +exclude patterns are, which means that beginning and trailing spaces are +trimmed and special characters must be escaped. See the documentation +above for more information. Comparing Snapshots *******************